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Preface 



This documenc is for process control software engineers who wish co wrice'application pro- 
grams co run on the I/A Series System. 

Readers are assumed co know chc C or FORTRAN programming languages. They are also 
assumed co be familiar wich che VENDC (or UNDO operating system. 
I/A Series reference Documents: 

SunOS Reference Manual I, II, III (BO 1 93LC) 

VENDC User Reference Manual (BO 1 93 BV) 

VENDC Programmers Reference Manual (B0193BX) 

VENDC Administrators Reference Manual (BO 1 93 BW) 

VENDCSuppbrt Tools Guide (BO 193CA) 

50 Series Program Development (BO 1 93LQ) — 
Program Development VENDC (B0193BA) 
Inter-Process Communications Calls (B0193BB) 
Human Interface Calls (B0193BD) 
• Miscellaneous Calls (B0193BE) 
Supervisory Setpoint Control (BO 1 93RY) 
System Messages (B 0 1 93CG) 

Revision information 

The following changes were made for Release 4.2: 

All calls in each Section were listed alphaberically. Added an incroduccion co each Section 
which lists the calls in the Section. 

Section 1. • Object Manager Concepts 

♦ Added CP40 co Objecc Manager Parameter Table. 
Section 2. C Calls co Gee/Sec Objecc Values 

♦ Added che following new calls: 

♦ sc_secval, sc_seccnf, sc_om_secval, st_omset_confirm, 
sc_sec_lisc and st_sedisc_confirm. 

♦ Modified che dan type and recurn code descriptions for che see- 
val, sec_confirmi orn_secval, om_sec_confirm, secvaljisc and 
sec_confirm_lisc. 

♦ Changed call sec_conftrm_lisc co sec_cnf_Iisc. 
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♦ Deleted return codes: NOT_SETTABLE, SECURED, 
TO_R£AL^CONV_ERROR, 

TO_INTEGER.CONV.ERRO R, i 
TO_STRING_CONV_ERROR, 
TO^BOOL.CONV.ERROR, from setval, se:_confirm, 
om_scrvaI, om_set_confirm, secvaLlist and sec_cnf_list. 
Section 3. C Calls to Access Update Sets of Variable 

♦ Added the new call: omwrstac. 

♦ Changed the value structure descriptions for "index" and 
"value" in the omwrite call. 

♦ Added EWRTTERROR recurn codes and changed return code 
descriptions for omwrite call. 



| Secrion5. FORTRAN Function to Get/Set Object Values 

1 • ♦ Added command strong co compile FORTRAN programs. 

| Appendix B. OM Error Codes 

| ♦ Added OM Error Codes, Appendix B.* 

I Appendix C OM Calls 

I ♦ Added OMC Calls 

i ♦ Added OM FORTRAN Calls 

I - 



viii. 



i i 



7. Object Manager Concepti 



Ail object « a construct chat the Object Manager can find by name, relieving you of the ne-d 
know „ IocaDon or pach flame> Tqc opcradng sysKm aucomacica]Iy ^ 

ables, Ietterbug names, and device logical names to be objects. Object Manager calls let you 
create and delete object names and read and write (get and set) object values. < 
Some of the Object Manager calls themselves invoke calls from other subsystems When this 
Happens, some return codes might actually come from the other subsystem. The exact code is 
passed back to che calling cask whenever possible, and che explanations are included with each 

The Object Manager supports two kindTofobjects: shared objects and process-control 
objects. Thar characterisdes are given below. 



Shared Objects Variables 



14 character name (maximum) 



Control Objects or Process 



You can creace, delete, read and 
write shared objects 



32 character name 



You can only read and write control objects 




1 .1 Object and Data Types 

An object can have one of the following' types: 



♦ VARIABLE 

♦ ALIAS 

♦ DEVICE/ 

. LETTERBUG 

♦ PROCESS 



A shared and process (control compound) variable 

An obi ccc whose value is che name of another objecc 

The leccerbug id or logical name of an external device like a sta- 
tion or printer 

A program in execution; a cask 

The regular shared VARIABLE objecc type can have any of che following data types: 
* CHARACTER 
INTEGER 
FLOAT 
STRING 

OiVLBOOL (character, values = true, false) 
OM_LNG JNT (long integer) 
OM_S J>KBOL (packed boolean) " 
OM_LJ?KBOL (long packed boolean) 
An ALIAS objecc type can only have STRING daca type. 



♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
♦ 
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The object types DEVICE and PROCESS are cypically, buc noc always, used with globaljind 
to get die address of die station where the device or cask is resident Since che objecc types 
D EVICE/LETTERBUG and PROCESS do noc have values, chey cannoc have any data types. 

The Objecc Manager docs noc restrict che data cype of concrol objects (VARIABLE object 
cype); chey can be of any data cype allowed by che control software. 

Integers are signed, unless che block parameter definition specifies otherwise. Reals adhere to 
the IEEE standard. 

The data types are stored in the status word of each objects value record structure. 

You have to make sure that the ipch include file is available, as the Object Manager include 
file "indud es n it as- well. 

1.2 Object Names — 

The maximum length for shared object names is 14 characters. Only alphanumerics and che 
underscore are permitted for types variable and alias. Types device and process can use any 
character Duplicate object names are permitted only if they are of different object types. 

Control objects (process variables) and device names are exceptions. The Objecc Manager 
does not restrict them, although their respective configurators do. Process variables can have 
names up to 32 characters to accommodate the compound, block, and parameter names. 

Refer to the Integrated Control Configurator - and System -Configurator documents for more 
information on these names. 

The complete OM name used to get ECB configuration and measurement parameters has the 
following format: 

<letterbug>_SC3 : <cBM_ID> . <I/A_name> 

where letterbug is replaced with the letterbug of the Tank Processor, FBMJD is replaced with 
che HIU letterbug, and l/A_name is the parameter name. 

Example: To get che pressure transmitter 1 frequency of a HIU with the letterbug of 

HTG131, which is connected to a Tank Processor with the letterbug of 
1 TP1013, che complete OM variable name is 

TP1013JECB:HTG13LC105. . 

All parameters that begin with- BYT axe character arrays. All parameters that begin with 
NAME are character arrays. All other parameters are floating point numbers. Refer to the 
control documents for parameter names. Names in OM open list should be uppercase. 

1 .3 The Import List and the Object Directory 

The import list contains the names of objects from ocher stations. Listed with each name is 
an index co Its address in che address cable. This list lets the Object Manager find objects .with- 
out sending out a broadcast to locate objects in remote stations. Objects are added to .che Use 
• as che resulc of user rcquescs. 
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If you are not going. co gee an object many rimes in a program, you are better off not bother- 
ing to import it. There is only one import list for che station, and all casks have co share it, so 
for efficiency, you should unimport all objects when you exit. 

The get/set calls can import objects as specified. The object directory contains all che shared 
objects created by tasks in che local station. They automatically become globally known when 
you create chem. The object directory contains poincers co che objects' values, if any. 

NOTE: You mus t close all OM lists before any exit from the program occurs. 

1 .4 Variable Scan Rates 

The Object Manager lets you specify a scan race for change-driven lists. This variable scan 
race is che race ac which che station chat is the source of che daca sends updaces co the scariori 
that opened che list. If you have programs written before variable scan rates were available, 
you should change your code to select che appropriate scan race. - 

You must specify che scan race for an OMOPEN Use in che om_header_node scructure in a 
C program. It is in Lncervais of 1/2 second A value of one causes a scan race of 1/2 second, a 
value of four a scan race of 2 seconds, and so on- ; 

The range of valid scan races is from 1/2 second cb 120 seconds. An invalid scan race is forced 
to che default value of 1/2 second. 

The following example is user code setting the scan race co 10 seconds before performing the 
OMOPEN 'request. 

#define SCAN_CYCLES 20 . z 

struct om_header_node *hdrjptr; ■ _ 

hdr_ptr = (struct ora_header_node*) 

malloc ( size of struct oca_hsadar_ncde} ; 
if (" hdrjptr != (struct om_header_noca* ) NULL )• 
( 

/* Set up for omopen. */ 
hdr_ptr->*scan_rate = SCANJ7/CLES; 



/* Perform 0M0?£^f. */ 

1 

else 

The FORTRAN format is as specified laccr for OMOPEN. 
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1 .5 Object Manager Parameter Table 

This cable defines sec and maximum values for certain Object Manager parameters by station 
A brief explanation of each icem in che cable follows che cable. 



I Description 


1 ^Qs 

| J VIA 


1 AP10P0 


PWs 


W I 5 


! CPs 


1 CMs ; 


Max # of OMOPPN T ;«-* 


1 i fin 


1 50 


l «.n 
1 50 


1 30 


1 (60/360) 


! 50 


Max # of Pninr* n^rT 


ICC* 






1 2}} 


! 255 j 255 


Max # of Shared Objects 


750# 


100/750 


750 




100 | 100 


Max # of Imported Objects 


I00# 


50 


50 


50 


1 50 ! 50 


Max # of Scanner En cries 


100# 


50 


50 


i o 


i 50/1600" 


50 


GETVAL Timeouc (seconds) 


12 


12 


12 


i 12 


1 150/12 


1 12 


SET_CONFIRM Timeouc (sed 


12 


12 


12 


12 


12 


12 


Max CHANGE Queues 


100# 


50 . 


50 


.5 


5/10— 


5 


Max * of IPC Connections 


30# 


12 


12 


12/30- 


12/30* 


12 



__"12 for W20 and CP10, 30 for WP30 and CP30/CP40. 
~50 forCPlO, 150 for CP30. 600 for CP40. 
— 5 for CP10. 10 for CP30/CP40. 
^V3*l release oa 50 Series maximums are configurable 

Some items are subject to constraints from other sub-systems (the number of connections or 
die number of points scanned, for example).. 

OMOPEN lists The maximum number of change-driven omopen lists. 

Points per List The maximum number of change-driven points for one omopen list. 

Shared Objects The maximum number of shared objects that can exist in a station at one 
time.. 

Imported Objects The maximum, number of objects that can be in an import list at one rime. 

Scanner Entries The number of scanner entries that one station can scan. Each entry corre- 
sponds to (part of) a list and can contain up to 20 points. The actual num- 
• ber of points a station can scan depends on the number of omopen lists 
and the size of each list* How many scanner entries are used for an 
omopen list is computed as follows: 

entries = (# points in station for list + 19)/20 

50 Series stations are an exception and contain up to 255 points per entry 
and therefore have a one to one relationship between a list and scanner 
entry. 

Example: 

A WP20 opens a list for 86 points that has 40 points in CPI, 45 points in CP2, and 1 point 
in CPS. 

CPt scanner entries = (40+19)/20 = 2 



K -A ) 
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CP2 scanner entries = (45+1 9)/20 = 3 

CP3 scanner entries = (l+19)/20 s 1 

For 50 Series = 1 entry per list 
CETVAL Timeout 

The number of seconds the Object Manager watts to receive data on a 
CETVAL request. If the object does not exist, the requester suspends for 
12 seconds. 

SBT.COlVFtMfTtmcoiiz 

The number of seconds the Object Manager waits to get a reply co a 
SET_CONFIRM request. If the station with the object is down, the 
requester suspends for 12 seconds. 

CHANGE Queues ■ . ' 

The number of queues available for open lists that want notification of 
changes. These queues are based on the process id in a particular staaon. 

1 .6 Object Manager Databases 

The databases 0 f the Object Manager for 50 Series reside in shared memory. This memory is 
divided into three partirions. The first partition is static and contains the static tables The 
second partition is a valloc pool for open lists. The third partition is another valloc pool ded- 
icated to strings created for shared objects (see Figure 1-1 and Figure 1-2). ' 
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Figure 1-L Object Manager Software Components • - 
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Figure 1-2. Ol^ectManagerSofraare Componmts(Cont.) 

1.6.1 Open Points Database 

The open points database is a linked list of descriptors (or header nodes) which describes lists 
of objects opened in this station. This database is further split into two portions: Remote 
Lists - those opened from remote stations, and Local Lists - those opened1>y applications . 
locally. Remote Lists do not have a Network Address Table. 

Separate locks (read and write) are maintained for each of the two* portions. Sines the Object 
Manager server operates (and locks) primarily on the Remote portion of the database, it does 
not usually interfere with user processes which access primarily the Local portion. As men- . 
tioned above, the lists are valloced from one disd.net partition. 

1.6.2 Scanner Database 

The scanner database is an indicator of which objects in an open list are to be scanned. All 
Remote Lists that are not opened for write only access, are scanned. Objects in Local Lists are 



6 
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scanned only if chc/ are local (created in chis staaon). Single connect control variables are 
only scanned once. Deleted objects in lists are skipped, after notification has been sent. 
The number of variable record pointers that can be contained in a row of the database (which 
corresponds to one list exactly), is equal to the maximum number of objects in a list (currendy 



list po- 


oped var 
ptr 


open var * 
ptr 




open var 













. 1 .6.3 Object Directory 

.The object directory contains the name of the shared object, the export status, and the 
pointer to the dynamically allocated value record (as described above, from a separate shared 
memory partition). Process names and device names have null value_rec pointers. A read 
lock and a write lock synchronizes access. 



entry . 




count 




name[] 


export 


value record ptr 




status 











1.6.4 Import Table 

The import cable scores variable names with indices co che Object Manager network address 
table. A read lock and a write lock synchronizes access. 



j •entry 
i count 




name(] 


network address Index 







1 .6.5 Object Manager Network Address Table 

This cable is an array of network addresses pointed co by chc imporc Use and che objecc direc- 
tory value records. A read lock and a wrice lock synchronizes access. 
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1 -6-6 Scanner Connection Table 

The scanner connection cable contains an array of network addresses for die connected sta- 
tions and the number of communication renys attempted for each connection. The connect 
status flag indicates whether the connection needs to be disconnected, and whether the entry 
is needed for the creation of a new connection. 



PSAP index 


channel id 


reference count 


retry count j status 













1 .6.7 Server Connection Table 

The server connection table contains the channel id and the Primary System Address Protocol 
(PSAP address) of all remote stations. 
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2. C Calls to Get/Set Object Values 



'S^S^tfS? (rtadins! Vf* (wri , dns) obi4Ct ^ * an."" 

ev are oat smted foe situations in which you only want a single transfer „f data. 

*Z£tZh!L \ d0CUmCn ^ 0»-«i-*«r Oft connecdonlea calls arc calls 

that ^ansfe d between tasb without having established an IPC connection (channel) 71 

J^StmT "* Wi<h IPC ^ MOneai0nlaS service. You do not have 



Table 2-1. C calls to Get/Set Object Values 




Section !»' 



i. 
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2.1 getval - Get the Value of an Object 



Get/Set Object Values 



getval gets chc value of che specified object An object is identified by ics name and cype. The 
object name can be eicher a shared object name or a compound name. If che object name is a 
compound name, then che object cype muse be variable. If che object name is a shared object 
name, then object cypes can be eicher variable or alias. Object cype shared variables can be 
daea cypes character, integer, long integer, float, string, boolean, packed boolean, and long 
packed boolean. Object type alias has a data cype string. There is no data value record for 
object types process and device, getval 'is synchronous; ic suspends your cask until che cransfcr 
is complete. 

Format: 

int getval (<naine>, <abj_eype>, <import:>, <value>, <status>, caca_leri>} 
char *name, *value; 

int obj_type, import, *data_len; 

unsigned int *scatus; 



Where: 
*name — 
obj_type 
import 

♦value 

* status 



~cata_len 

Return Codes: 
OM — SUCCESS 
EMOTFOUND 



A character poincer co che name of che object. 

The named objects cype; VARIABLE or ALIAS. 

1 * place the objects name on the import list. 
0 = do not place it on the import list. 

A pointer to che location where the Object Manager is co put che objects 
value. Specify its size in bytes using cata_leri. 

A pointer to che location where the Object Manager is to return che 
pbjects status (data type). An ALIAS object type can only have STRING 
daca type. 

The regular shared VARIABLE object cype can have a data type of CHAR- 
ACTER, INTEGER. FLOAT, STRING, OMJBOOL, OM_LNGJNT 
(long integer), OM_S _PKBOL (packed boolean), or OM_L_PKBOL 
(long packed boolean). 

The Object Manager does noc restrict process VARIABLE data types, buc 
they can be of cypes CHARACTER, INTEGER, REAL STRING, 
OM_BOOL (boolean), and LONG JNT and POINTER (boch long inte- 
ger). 

Incegers are signed, unless che block paramecer definition specifies ocher- 
wise. Reals adhere co che IEEE scandard. 

A poincer co che length (bytes) allocated for value. OM returns actual 
length. 

No errors. 

Object noc found (locally or globally). 



I- 
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E3ADTYPE 
ENOSPACE 
E3ADNAME 
E3ADLSN 
EjroVALUE 
E3ADVREC 
EIPCSET 
TO_BIG 
.Call Notes 
1 



Illegal object type. 

No memory available; no value returned. 
Invalid object name. 
Shared variable is coo big for data_len. 
Specified objecc cype has no "value". 
"Value" is corrupt invalid dara cype. 
You have an unspecified IPC error. 
Process variable is coo big for data_len. 



Placing a local objcct.(one found in the same station) on the import list is unnec- 
essary, so for local objects getval ignores that option. However, the value is still 
returned. 

2. If you get an error return, the Object Manager may still return a value, but it is 
garbage. Do not send the returned value to useful data areas unless there is no error 

. return, _ 

3. Return code ENOTFOUND might mean chac the object does not exist locally or 
globally. If the object exists in a remote starion, then that station might be down. 
In either case, The Object Manager removes the objects name from the import 
list. 

4. If you do not make data_len large enough* value will be too small to hold the 
returned value. In such a case getval returns as much data in value as will fit. 

5- If datajen is coo large, value will contain unused bytes, getval does not close-up 
this unused memory space. 

6, Status, data_len, and value are modified regardless of error return.^ 
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2.2 getvaljist - Get the Value of an Object 



gewaLJjst gets the value of die specified object- This call is a variation of the om_getvd call. Ic 
differs only in che way che PSAP is specified. 

Instead of che ?sa? _ptr input argument used in om^gerjaK), the getval_liszQ call uses an 
<open_id> and an <ov_inde:o argument- The < open_id> argument specifies che ID of an 
open variables list. The list need not be optimized, but ic must currendy be opened. The 
<ov_index> specifies che index of a variable entry within the list. The variable must be con- 
nected. It is assumed that the variable in the list and the target object reside in the same sta- 
tion. (The variable and the object may or may not be one in the same.) The PSAP associated 
with that variable identifies the station to which the gecval message will be sent. The message 
will noc be broadcast. 

getval_Ust is syt^hronous; it suspends your task until che transfer is complete. 
Format: 

int getval_list (<name>, <obj_type> # <ixnport>, <value>, <status>, <data_len>, 
<open_id>,<"ov_index>) ' 



caar 
int 

unsigned int 



♦name, *value; 

obj_ty?e, import: , *data_ler., o?en_ic, ov_index; 
♦status; 



Where: 
*naae 
obj_type 
import 

♦value 

♦status 



♦dataller. 
open_id 



A character pointer to the name of the object. 

The named objects type; VARIABLE or ALIAS. 

1 = place che objects name on che import list. 
0 * do not place it on che import list. 

A pointer co che location where che Object Manager is to put the objects 
value. Specify its size in bytes using data_len. 

A pointer to the location where the Object Manager is to return the 
objects status (data type). An ALIAS object type can only have STRING 
data type. . 

The regular shared VARIABLE object type can have a data type of CHAR- 
ACTER, INTEGER, FLOAT STRING, OM_BOOL, OM_LNGJNT 
(long integer), OM_SJ?KBOL (packed boolean), or OM_LJ>KBOL 
(long packed boolean). 

The Object Manager does noc restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, REAL, STRING, BOOL 
(boolean), and LONG JNT and POINTER (both long integer). 
Integers arc signed, unless the block parameter definition specifies other- 
wise. Reals adhere to che IEEE standard. 

A pointer to the length (bytes) allocated for "value." OM returns actual 
length. 

ID of an open variables list. 



f 
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Index of a variable entry within the list. 



ov_ index 
Return Codes: 
OM_SUCCESS 
ENOTrOCJND 

E3ADTYPE 
ENOSPACZ 
E3ADNAME 
E3ADLZN 
ENO VALUE 

S3ADVREC 
' SIMPFULL 
E3AD INDEX 

ENOTOPENED 
ENOTACTIVZ 
E1PCRET 
Call Notes: 

1. Placing a local object (one found in the same station) oh the import list is unncces 
sary, so for local objects getvaljist ignores that option. However, the value is still 
returned. - " ■ % 

2. If you get an error return, the Object Manager may still return a value, but it is 
garbage. Do NOT send the returned value to useful data areas unless there is no 
error return). ' 

3. If you do not make datajen large enough, value will be too small to hold the 
returned value. In such a case getval returns as much data in value as will fit. 

4. - If datajen is too large, value will contain unused bytes, getval Jiist does not close- 

up this unused memory space. 

5. Status, data Jen, and value are modified regardless of error return. 



No errors. 

The name to get waj found in the import list, but IPC returned an error 
which indicates the message was rejected because station may be down. 
The object name is removed from the import list. '■ 

Illegal object type argument. 

No memory available; no value returned. 

Invalid object name. 

Shared variable is too big for datajen. 

Specified object type has no "valueUThe caller requested to get the value 
of an object type process or device. 

* Value" record is corrupt, invalid data type. 

Import table full; valee is returned. 

The specified ov_index is out of range, or selects an entry which is not cur- 
rendyinusc. ■ . - 

The specified open Jd does not correspond to an open variables list. 
Not registered with IPC for connectionless service. 
You have an unspecified IPC error. 



801 33SC - October 31, 1995 ^ : ^\ 



Section 2 



) Get/Set °bject Values 



23 om^getval - Get the Value of an-Object 

nerval gas die value of a specified object. This call is a functional superset of the mfi 
caU. It uses Primary System Address Protocol (PSAP) pointer as an addirional anmrnraJlFAc 
pointer value is NULL, om^etvaS) behaves as a gmmQ call, and the jrarf mes^e is broad- 
cast. om^etvaL is synchronous; it suspends your cask until the transfer is complete! 
Format: 

int oni^etval(<name> / <obj_t:ype> # <iniporc> # <valu6> / <3cacus> <dat= > 
<psap_ptr>) ' av —- ^' 

char *naae, *value; 

lnt obj_type, iaiport, *data_lan; 

unsigned int /^status; 

PSAP-ADDR *psa?_ptr; 



Where: 
*name 
cbj_typ e 
import . 

* value 

w 3tatus 



*data_len 
psa?_ptr 

Return Codes: 

OM_SUCCESS 



A character pointer to the name of the object. 

* The named objects type; VARIABLE, ALIAS. 

1 = place the objects name on the import list. 
0 = do not place it on the impon list. 

A pointer to the location where the Object Manager is to put the objects 
value. Specify its size in bytes using data_lan. 

A pointer to the locadon where the. Object Manager is . to return the 
objects status (data type). An ALIAS object type can only have STRING 
datatype, - 

The regular shared VARIABLE object type can have a data type of CHAR- 
ACTER, INTEGER* FLOAT, STRING, OM_BOOL, OM LNG_INT 
Gong integer), OM_S_PKBOL, n or OMJL_PKBOL 

The Object Manager does noc restrict process VARLABLE data types, but 
they can be of types CHARACTER, INTEGER, REAL, STRING, BOOL 
(boolean), and LONGJNT and POINTER (both long integer), 
OM_S_PKBOL (packed boolean), and OM_L_PKBOL (long packed 
boolean). 

Integers are signed, unless the block parameter definition specifies other- 
wise. Reals adhere to the IEEE standard. 

A pointer to the length (bytes) allocated for value. OM returns actual 
length. 

Pointer co the PSAP identifying the station on which che variable is found. 
A value of (PSAP_ADDR *)NULL indicates chac no PSAP has been pro- 
vided, so che station must be found using a broadcast message. 

No errors. 
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ENOTFOUND 

E3ADTYPE 
. ENOSPACE 

E3ADL2N 
ENOVALCJE 

E3ADVREC 
EIHPFULL 
ENOTACTIVE 
EIPCR2T 
Call Notes: 



The name co gee was found in che imporr Use. buc IPC returned an error 
which indicates the message was rejected because station may be down. 
The object name is removed from the import list. 

Illegal object type argument 

No memory available; no value returned. 

Invalid object name. 

Shared-variable is too big for datajen. 

Specified object type has no "value". The caller requested to gee the value 
of an object type process or device. 

"Value" record is corrupt, invalid data type. 

Import table full; value is returned. 

Not registered with IPC for connectionless service. 

You have an unspecified IPC error. 



1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects *77^rx*z/ ignores chat option. However, the value is still 
•returned. 

2 - %pu get an error return, the Object Manager may still return a value, but it is 
garbage. Do not send the returned value to useful data areas unless there is no error 
return. m • 

3. If you do not make data Jen large enough, value will be too small to hold the 
returned value. In such a case om_getval returns as much data in value as will fit. 

4. If datajen is too large, value will contain unused bytes, om _getvaldocs not close- 
up this unused memory space, 

5. Status, datajen, and value are modified regardless of error return. 
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2.4 om_set_confirm - Set the Value of an Object ' 

om_se!_confirmscxs the value of die specified object and waits for confirmation chat it was sec 
This call is a functional superset of the s&_confzrm call. It uses a PSAP argument co specify the 
' station to which the SETVAL message is sent. Use of the argument eliminates the need to 
broadcast the SETVAL message. This call worb for shared variables, process variable, and 
aliases. om_set_confirm is synchronous; ic initiates the SETVAL message and waits for a 
response before returning control co your process/task. 
Format: 

int om_set_confirm(<name>,<obj_t^ l sn> 
<?sap_ptr>) . ~ 

char *name, * value; 

* nC obj_type, import, dataller.; 

unsigned int *status; 

PSAP_ADDR ♦psapjtr; 



Where: 
*name 
obj_type 
import 

*va!ue 

♦status 



<iata_len 
*?sap_ptr 

Return Codes: 
OM_SUCCZSS 
E3ADTYPE • 



— A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list, 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes using data_len if 
it is a string or process variable. 

A pointer co the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OMJLNGJNT (long integer), OM_SJPKBOL (short 
packed boolean), or OM_LJ?KBOL (long packed boolean). 
The Object Manager- does not restrict process VARIABLE data types. All 
: shared VARIABLE -data types are supported plus CIO_SHORT (unsigned 
character). 

• The length (in bytes) allocated for "value*. This is needed for STRING 
daca types and all process variables (0 defaults to size of float). 

A pointer to the objects station PSAP address. A value of (PSAP_ADDR x ) 
NULL indicates thac no PSAP has been provided (the call acts exactly the 
same as a set_confirm call). 

The set request has been initiated successfully. 
The specified data type is not supported. 



a- o 

Section 2. C Calls to Cet/Set Object vQs 



(f^ EV 32484940 k 

93 BC- October 31, 1995 



The specified daca type does noc. match che actual data cype (shared vari- 
ables only). ' 1 

For ALIAS, che data type is noc STRING. 

For shared VARIABLE data cype OM.BOOL, specified value is noc 1 
(True) or 0 (False). 

Objecc name coo long. 

Process variable name wich object cype noc equal co VARIABLE 

For STRING daca cype, specified string length coo long or < = 0. 

For STRING daca cype, specified scring length longer than actual serin* 
length. 53 

Object cype DEVICE or PROCESS was specified. 
Variable is secured. 
Shared variable value record bad. 
Object noc found. 

Object not found in specified scation. A station is specified by import cabl^ 
entry, PSAP parameter, or list ID and index parameters. 
Caller not activated with IPC. 
System resource availability problem. 
IPC returned an unspecified error. 
Return Code Notes: 

1- OM error codes are negative (refer to OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Messages). 

Call Notes: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects om_setjconfirm ignores that option. 

2. If a value is successfully set, its BAD and OOS status bits are aucomacically resec. 



E3ADNAME 



ESTRLEN 



ENOVALUE 

ESZCtTRE 

E3ADVREC 

ENOCONrIRM 

ENOTFOUND 

ENOTACTIVE 

ENOSPACE;: ■:. . 
EIPCRET. r 
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2.5 om^setval - Set the Value of an Object 

om setoatscxs the value of chc specified object. This call is a functional superset of che wmd 
call. Ic provides a PSAP argument co specify che station to which the amjmd message is to 
be sent Use of che PSAP argument eliminates the need co broadcast the SETVAL message, 
This call works for shared variables, process variables, and aUases.-^xWis asynchronous if 
che object is noc in che local station; it initiates the 
SETVAL message and returns control to your process/cask 
Format: 

int ora_setval. (<name>,<oSj.type> # <iinporw> # <vaIus> # <sSacus> # <data le-> 
<?sap_ptr>) - ie " ' 



char 
int 

unsigned int 
PSAP_ADOR 



*name, * value; 

°b j_tY?«, import:, data_len; 

*status ; 

*psa?l^tr; 



Where: * 
*name 
°kj_type 
import 

*value 

*status 



cat'a_len 
*psap_ptr 

Return Codes: 

OM.SUCCZSS 

E3ADTYPE 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes* using daca_len if 
it is a string or process variable, 

A pointer co the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM.BOOL (byte with True/Rise 
values only), OMJLNG JNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_L_PKBQL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT-(unsigned 
character). , 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaulcs co size of float). 

A pointer to the object's station PSAP address. A value of (PSAP_ADDR *) 
NULL indicates that no PSAP has been provided (che call acts exactly the 
same as a setval call). 

The set request has been iniciaced successfully 
The specified daca.cype is noc supported. 
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ENCVALUH 
- ESZCUHH 
E3ADVREC 



The specified daca cype does noc match 'che actual data cype (shared vari- 
ables only) . See Note 3. 

For ALIAS, the daca type is not STRING. 

For shared VARIABLE daca cype OM.BOOL soecified value is noc I 
(True) o r 0 (False) . See No ce 3 . 

Object name coo long. 

Process variable name with object cype noc equal to VARIABLE. 

For STRING daca cype, specified string length coo long or < = 0. 

For STRING daca cype, specified string length longer than accual serin* 
length. See Note 3. 3 

Object cype DEVICE or PROCESS was specified. 
VARIABLE is secured. See Note 3. 
Shared variable value record bad. See Note 3. 
Return Code Notes: 

1. OM error codes are negative (reTer to OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refe- to the 
document System Messages). 

3. These error cases are returned only if the variable is local. 
Call Notes: . ... 

1- Sincevsfeis call is asynchronous, it cannot wait for return codes from remote sta- 
tions. Thus all returns concerning the object to be set can only come from the 
local station. Control variables can only be local in a Personal "Workstation fa PW- 
CorPW-FB). -' 1 

2. Placing a local object (one found tn the same station) o n the import list is unneces- 
sary, so for local objects om_setval ignores chat option. 

3. If a value is successfully set. its BAD and OOS status bits are automatically reset. 



2.6 set_confirm - Set the Value of an Object 
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^t^confirm ses die value of die specified object and waits for confirmadon thac it was sec. 
This call works for shared variables, process variables, and aliases. set^confiTm is synchronous; 
it initiates the SETVAL message and waits for a response before returning control to your p 
-cess/task. 

Format: 

int se t_conf irm ( <aame> , <cbj_type>, <imporc>, <vaiue>, <stacus>, <data_ls:i>) 
char *narae, *value ; 

int obj_type, import, cata_len; 

unsigned int *status; 



Where: 
*name 

import 
"value 
♦status 



data_len 

Return Codes; 

OM^SUCCZSS 

E3ADTYPE 



E3ADNAME 



A pointer to the name of die object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list; 

A pointer to the values location. Specify its size in bytes using data_len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15)* 

An ALIAS object type can only have STRING data type. ** 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OMJBOOL (byte with True/False 
values only), OM_LNG_INT (long integer), OM_S_PKBOL (short 
packed boolean), or OM:_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value"- This is needed for STRING 
data types and all process variables (0 defaults tC size of float). 

The set request has been initiated successfully. 
The specified daca'cype is not supported. 

The specified daca type docs not match the actual data type (shared vari- 
ables only). 

For ALIAS, the daca cype is noc STRING. 

For shared VAIUABLE data cype OiVLBOOL, specified value is not 1 
(True) or 0 (False). 

Object name coo long. 

Process variable name wich object cype noc equal co' VARIABLE. 
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ESTRLEN 



For STRING data type, specified string length coo* long or < = 0, 
kn<^xt^ NG ^ SpCdRcd 5Cfing lcngth lon S cr acmal s ™g 

Object type DEVICE or PROCESS was specified. 
Variable is secured. See No ce 3 . 
Shared variable value record bad. 
Object not found. 

• Object not found in specified station. A stacion is specified by import cable 
entry, PSAP parameter, or list ID and index parameters. 
Caller not activated with IPC. 
System resource availability problem. 

IPC returned an unspecified error. 
Return Code Notes: 

1. OM error codes are negative (refer to OiVf_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Messages) \ 

Call Notes: " * . " 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary <$q> for local objects set_confirm ignores that option. 

2 : If a Vsdue is successfully set, its BAD and OOS status bits are automatically reset. 



ENOVALCTE 

ESECURE 

E3ADVREC 

ENOCONFIRM 

ENOTFOUND 

ENOT ACTIVE 

ENOSPACS 

EXPCRET 



Section 2t""^)o Cer/Se. Object Values' 



j 2.7 set_cnfjist- Set the Value of an Object 

'Zffi:*** f* ^ ° f ** Spt6Bed ° bjCCt - This ^ b a of che am s<r confirm 

calL It differs only in the way the PSAP is specified. °™-^-Confirm 

.The ID of a currency open (optimized or unoprimized) Use and che index of a variable entry 
che target object reside in the same station. The PSAP associated with that variable identifies 

Format: 



char 
int _ . 
unsigned int 



'name, * value ; 

°bj_type, import, data_len, opened, ov_index; 
*status; 



.Where: 
*name 
obj^type 
impprc 

•value 

♦status 



data.len 

cpen_ic 
ov_index 
Return Codes: 

OM_SUCC ES3 
E3ADTYPE 



A pointer to tEe name of the object. 
The named objects type; either VARIABLE or ALIAS. 
1 ■ Place the objects name on the import list. 1 
0 a Do not place the objects name on jhe import list. 

A pointer to the values location. Specify its size in bytes using data_l en if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data tvoe 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE objea type can have a data type of CHARAC- 
TER, INTEGER. FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OM.LNG JNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_LJ>KBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE daca types are supported plus CIO_SHORT (unsigned 
character). s 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

ID of open variables list that contains the variable co set. 

Index of a variable entry within the list. 

The set request has been initiaccd-successfully. 
The specified daca cype is noc supported. 
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The specified daca cype does noc match che actual daca type (shared vari- 
ables only). 

For ALIAS, che data cype is noc STRING. 

For shared VARIABLE daca cype OMJOOL, specified value is noc 1 
(True) orO (False). 

Object name coo long. 

Process variable name with object cype noc equal co VARIABLE. 

For STRING daca cype, specified string length coo long or < = 0. 

For STRING daca type, specified string length longer than actual serin* 
length, ? 

Object cype DEVICE or PROCESS was specified. 
Variable is secured. See Note 3. 
Shared variable value record bad, 
Objccc not found. 

Object not found in specified scacion. A station is specified by import table 
entry, PSAP parameter, or list ID and index parameters. 

Caller noc activated with IPC. 

System resource availability problem. 

IPC returned an unspecified error. 

Specified list not open. 

Specified index greater than size of list. Specified index entry not con- • 
nected - 

Return Code No ces: 

1. OM error codes are negative (refer co OM_ECODE-H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Messages) . 

Call Notes: 



E3ADNAME 



ES7RLEN 



SNOVALUE 

ESSCURE 

E3ADVREC 

EN0C0NFI5M 

ENOTFOCJND 

ENOTACTIVE 
ENCSPACE 
EI PC RET S V" 
ENCTOPENED 
E3 AD INDEX 



1. - Placing a local object (one found in the saine station) on the import list is 

»ry, so for local objects setjmfjist ignores that oprion. 

2. If a value is successfully sec, its BAD and OOS status bits are automatically 



unneces- 



resec. 
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2.8 setva! - Set the Value of an Object 

Wsea che value of che specified object. This call works for shared variables, process van- 
abte, and aliases, stalls asynchronous if the object is noc in the local station; ic initiates che 
on i val message and returns control to your process/cask. 
Format: 

ins «tval(< r ^e>,<3b^ 

char *naae, * value; 

lnt obj-type, import, daCa_len; 

unsigned int *status; 



Where: 
*name 

import 
*value 
"status 



data_len 

Return Codes: 

OM_SUCCESS 

E3ADTYPE 



£3 AO NAME 



A pointer to chc name of the object. 

The named objects cype; either VARIABLE or ALIAS. * 

1 = Place the objects name on the import list. 

0 = Do not place chc objects name on the import list. 

A pointer to the values location. Specify its size in bytes using data_lan if 
' it is a string or process variable. 

A pointer to the location where you have stored the objects data evre 
(range 1-15). . ™ 

An ALIAS object type can only have STRING daca cype. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OM.LNG JNT (long integer), OM_SJ?KBOL (short 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO^SHORT (unsigned 
character). ° " 

The length (in bytes) allocated for "value*. This is needed for STRING 
data types .and all process variables (0 defaulcs co size of float). 

The sec request has been initiated successfully 
The specified data cype is not supported. 

The specified daca cype does noc macch the actual daca cype (shared vari- 
ables only). Sec No ce 3. 

For ALIAS, che daca cype is noc STRING. 

For shared VARIABLE daca cype OiVLBOOL, specified value is noc I 
(True) or 0 (False). See Noce 3. 

Objecc name coo long. 

Process variable name wich objecc cype noc equal co VARIABLE. 
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■stub* For STRING data cypc, specified string length too long or < = 0. 

For STRING data type, specified string length longer than actual strin* 
length. See Note 3. ° 

ENO value Object type DEVICE or PROCESS was specified. 

ssecure ^ VARIABLE is secured. See Note 3. 
E3ADVREC Shared variable value record bad. Sec Note i. 

Return Code Notes: 

1- OM error codes are negative (refer to OM.ECODE.H or Appendix B). 

2. Control and I/O (Compound Processor) returns positive error codes (refer to the 
document System Masaga). . 

3. These, error cases are returned only if the variable is local. 

Call Notes: " 

.1. $ince this call is asynchronous, it cannot wait for return codes from remote-sta- 
aons. Thus all returns concerning the object to be set can only come from the 
Cor m-FB) 01 VariaWe ^ 0aiy be CeaUn a PcrsonaI Workstation Xa PW- 

2. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objecn W ignores that option. ' \ aimneces , 

3. Ifa^ue is successfully set, its BAD and OOS status bits are automatically reset. 
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2.9 setvaljist - Set Value of an Object 

Rvalue of chc spcdfiedobjccr.Thisoilbaviriacionofche^ Ic 
differs only in chc way chc PSAP is specified. - " Ic 

The ID of a currendy open (optimized or unoprimized) list and che index of a variable encrv 
m chc be arc specified. The variable muse be connected. It is assumed chat che list variable^ 
target object reside in the same station. TheJSAP associated wich that variable identifies 
Aes^aon co which the SETVAL message is sen, W.&is asynchronous; it initiates the 
or, i yal message and returns concroi co your process/cask. 
Fonnac 

char *name, *value; 

lnt obj-type, import:, dataller., oper._id, ov_index; 

unsigned int *status; 



Where: 
♦name 

import 
*value 
*status 



<^ta.ien 

open_id 
ov^index 
Return Codes: 

SUCCESS 
H3ADTYPE. 



A pointer to the name of che object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects- name on the import list. 

A pointer to die values location. Specify its size in bytes using data len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data tvne 
(range 1-15). 79 
An ALIAS objea type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte with True/False 
values only), OMjlNG JNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VAJUABLE data types. All 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). m m 3 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaults co size of float). 

ID of open variables list that contains che variable co sec. 

Index of a variable entry wichin the list. 

The sec requesc has been initiated successfully. 
The specified data type is noc supported. 
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van- 



The specified data type does not match the acruai data type (shared 
aoles only). See Noce 3. 

For ALIAS, the daa type is not STRING. 

I Irue) or 0 (False). See Note 3. 
Objea name too long, 

Process variable name with objea type not equal to VARIABLE. 
For STRING data cype. specified string length too long or < = 0 

tegSSot 3. W **** bnSi ' 0ng « *» ^ «** 
Objea type DEVICE or PROCESS was specified. 
VARIABLE is secured. See No te 3. 
Shared variable value record bad. See Note 3, 
Specified list no t open. 

Specified index greater than size of list. Specified index entry not con- 
neaed. 

Return Code Noces: 

1- OM error codes are negative (refer to QMJECODJE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to the 
Raiment System Messages). * vrcrer to tne 

3. These error cases are returned only if the variable is local. 
Call Notes: 

1. Placing a local objea (one found in the same station) on the import list is unneces- 
sary, so for local objects setvaljist ignores that option. . 

•2. If a value is successfully set, its BAD and OOS status bits are automatically resec. 



E3ADNAME 



ESTRL2N 



ENOVALCJE 
ESECURS 
E3ADVREC 
ENOTOPENED 
~E3AD INDEX 
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| 2,1 0 st.omseLconfirm - Set the Value and/or Status of 
an Object 

st.oms^conjtrmsev the value and/or die status of the specified object. This call is a func 

aortal extension of the om_se!_conf™ call. A status mask and a status data parameter allow 
! Z ^^on of object status bits to be set or reset. A status only parameter allows the writ- 

ing ot status without an accompanying data value. This call works for shared variables, process 
I variables, and aliases. st_omset_conftrm is synchronous; it initiates the SETVAL message and 

waits tor a response before returning control to your process/task. 

Format: - 

I ^^ S V Met - COnfi ^ (<nMe> ' <obj - t ^ e> ' < ^ or£> '^ a i«a>.<s5:aC"s> 
I <aaca_len>, <psap_ptr>. <st_data>, <st_mask>, <st_only>, <appl_work>] ' 



cnar 
int 

unsigned int 
PSAPjiDDR 



*name, *value, *appl_work; 
°oj_type, import, data_len; 
•scatus, st_data, s£_mask, sc_oriIy; 
*psap_ptr; 



"Where: 
*name 
°bj_type 
import 

*value 

•status 



data_len 



*Psap_pt3 



st_cata 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name On the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location: Specify its size in bytes using data_ien if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data tvoe 
(range 1-15). /F 
An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byte widvTrue/False 
values only), OM_LNG_INT (long integer), OM_S__PKBOL (short 
packed boolean), ot OM_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. AH 
shared VARIABLE data types are supported plus CIO_SHORT (unsigned 
character). . c 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

A pointer to the objects station PSAP address. A value of (PSAP ADDR ") 
NULL indicates that no PSAP has been provided (the call acts exactly the 
same as a set_confirm call). 

Object status data bits. This word specifies the desired setting for the bits- 
specified in st.mask Only bits defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed to be set/reset. 



o 
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appl_work 



Return Codes: 

OM_SUCC£SS 
E3ADTYPE 



Object status mask bits. Bits set in this word specify the bits co set/rese* 
according co their setting in the daca word. If 5C _mask is NULL, the call 
perfornu > like: > WcalL If sc.mask is NULL, the call automarically resets 
BAD and OOS if a successful value sec is performed. 
- If st_oniy is TRUE (non-zero), only a status sec is performed. The daca 
value is noc sec. If st.only is TRUE and sc_mask is NULL che call is a 

A pointer co a workstation ID string. For application programs, soenfV 
OiVLAPPLICATION (defined in om_udef.h). * * 



The set request has been initiated successfully. 
The specified daca cype is noc supporced. 

The specified daca type does noc match che actual data cype (shared vari- 
ables only). 

For ALIAS, the data type is not STRING. 

For shared VARLABLE data type OM.BOOL, specified value is noc 1 
(irue) or 0 (False). 

Object name too long. 

Process variable name with object type not equal to VARIABLE. 

For STRING data type, specified string length too long or .< = 0. 

For STRING data type, specified string length longer than actual serine 
length. ° 

Object type DEVICE or PROCESS was specified. 
Variable is secured. See Note 3. 
Shared variable value record bad. 
Object not found. 

Object not found in specified station. A station is specified by import able 
entry, PSAP parameter, or list ID and index parameters. 

Caller not activated with IPC. 

System resource availability problem. 

IPC returned an unspecified error. 

Invalid bits set in write status mask. Valid bits are defined in om_udef.h. 
Workstation ID name invalid length (must be exacdy 13 characters) 
Return Code Notes: 

1. OM error codes are negative (refer to OMJCODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Messages). 



E3ADNAME 



ES7RLEN 



ENOVALUE 

ESECURE 

E3A0VREC 

ENOCONFIRM 

ENOTFOUMD 

EN0TAC7IVE 

ENOSPACE 

EIPCRET 

EBAOMSX 

E3ADWXSTA 



3. These error cases returned only if the variable is local. 
Call Notes: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects st_amsev_confirm ignores- that option. 

2. For processVariables, BAD and OOS are always cleared before the masked status • 
wnce is performed. 
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2.11 st_om_setval - Set the Value and/or Status of an - 
Object 

*_*m_«.Wsets the value and/or;che status of the specified object This call is a functional 
extension of the om_setual call. A status mask and a status data parameter allow the specifica- 
tion of object status bits to be set or reset.- A status only parameter allows the writing of status 
without an accompanying data value. This.call worb for shared variables, process variables, 

• StW 5 * St -° m - SetvaIls asynchronous »f the object is not in the local station; it initiates the 
oETVAL message and returns control to your process/cask. ' 

Format: 

inc st_om_setv^l(<nane> / <obj_cype>;<import> 1 <vaiue>,<ssa-^s>,«:ac» len> 
<?sap_pcr> < <sc_daCa> / <se_raask>,<se_only> < <appl_wor:<>) - ~ * '. 

ci * ar 'name, »value, *appl_wcrk; 

inc obj_type, labors, daea_lari; 

unsigned int. -scatus, st_daea, se_mask, st_onIy; 

PSAP_ADDR "psapjer; ' ■ 

"Where: ~ 

•nana A pointer to the name of the object. 

obj.type The named objects type; either VARIABLE or ALIAS. 

in ^ 50rt: 1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes using data_Len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. " - 

The shared VARIAB LE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OM_BOOL (byre ^th True/False 
values only), OM_LNG_INT (long integer), OM_S_PKBOL (short 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types are supported plus CIO_$HORT (unsigned 
character). 

daea_len The length (in bytes) allocated for "value." This is needed for STRING 

data types and all process variables (0 defaults to size of float). 

*?sap__ptr A pointer to the objects station PSAP address. A value of (PSAP_ADDR ") 
NULL indicates that no PSAP has b ctn provided (ehc Coll acts exactly che 
same as a setval call) , . 

sc^data Object status data bits. This' word specifies the desired setting for che bits 

specified in st_masb Only bits defined in om_uder.h (BAD, OOS, and For 
process control variables only ACK) are allowed co be sec/resec. 



♦value 
♦status 
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st_raasfc 



appl_work 



Objca status mask bits. Bits set in this word specify the bits to set/ reset 
according to their setting in che data word. If st_mask is NULL, the call 
performs like a senalcslL If st_mask is NULL, the call automatically resets 
BAD and OOS if a successful value se: is performed. 

If st_only is TRUE (non-zero), only a status set is performed. The data . - 
value is not set. If st_oniy is TRUE and sc_mask is NULL, the call is a 
NOP. 

A pointer to a workstation ID string. For aoolicarion programs, soedfy 
OM^APPUCATION (defined in om_ude£h). 



Return Codes: 
OM_SUCCZSS 
E3 AD TYPE 



The set request has been initiated successfully. 
The specified data type is not supported. 

The specified data type does not match the actual data cype (shared vari- 
ables only). See Note 3. 

For ALIAS, the data type is not STRING. 

For shared VARIABLE data type OM_BOOL, specified value is not 1 
(True) or 0 (False). See Note 3. 

Object name too long. 

Process variable name with object type not equal to VARIABLE. 

For STRING data type, specified string length too long or < = 0. 

For STRING data type, specified string length longer than actual string 
length. See Note 3. 

Object type DEVICE or PROCESS was specified. 
VARIABLE is secured. 
Shared variable value record bad. See Note 3. 

Invalid bits set in write status mask. Valid bits are defined in om_udef.h. 
Workstation ID name invalid length (must be exacdy 13 characters). 
Return Code Notes: 

1. OM error codes are negative (refer to OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) returns positive error codes (refer" to the 
document System Messages) . 

3. These error cases are returned only if che variable is local. 

4. If a value is successfully set, its BAD and OOS stacus bics are automatically reset. 
Call Notes: 

1. Since this call is asynchronous, it cannot wait for return codes from remoce sta- 
• tions. Thus all returns concerning che object co be se: can only come from the 
local station. Control variables can only be local in a Personal Workstation (a PW- 
CorPW-FB). 



E3ADNAME 



ESTRLEN 



ENOVALUE 

ESECUKE 

E3A0VREC 

E3ADMSK 

EHADWXSTA 
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2. Placing a local object (one found in che same station) o n the import list is unneces- 
sary, so for local objects st_om_setval ignores that option. 

3. For process control variables, BAD and OOS are always cleared before the masked 
status write- is performed. 
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| 2.12 st_setcnf - Set the Value and/or Status of an 
Object 

J sr_sexnfsev die value and/or die status of die specified object. This call is a functional exten- 
sion of die set^cqnfirm call. A status mask and a status data parameter allow die specification 
of object status bits co be set or reset. A stacus only parameter allows the writing phtatus with- 
out am accompanying data value. This call works for shared variables, proccss°variables, and 

I aliases. st_setcnf\s synchronous; it initiates the SETVAL message and waits for a response 
before returning control to your process/task. 
Format: 



I xnfc st_setcn 

I <sc_data>,< s 

I char 

| int 

I unsigned 

Where: 
*name 
obj_type 
iamort * 

♦value 

•status 



f {<nasie>, <obj_type>, <iaport>, <vaiue>, <stasus>, <cata_ler.>, 
t_raaslc>, <st_only>, <appl_work>) 



int 



'name, 'value, *appl_work; 
obj^type, import, dataller.; 
♦status, st_data, st_mask, st_or:ly; 



cata_len 
st_cata 

stomas !< 



A pointer to the name of the object. 

The named objects type; either VARIABLE or ALIAS. * 

1 - Place the objects name on the import list. 

0 = Do not place the objects name on the import list. .'. 

A pointer to the values location. Specify its size in bytes using dataller, if 
it is a string or process variable. 

A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, ELOAT, STRING, OMJBOOL (byte with True/False 
values only), OM_LNGJNT (long integer), OM_S_PKBOL (short 
packed -boolean), or OM_L_PKBOL (long packed boolean). 
"The Object Manager does not restrict process VARIABLE data types. All 
. shared VARIABLE data types are supported'ptus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaults to size of float). 

Object status data bits. This word specifier the desired setting for the bits 
specified in st_mask Only bits defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed to be sct/resec 

Object status mask bits. Bits set in this word specify the bits to set/ reset 
according to their setting in the data word. If st_mask is NULL, the call 
performs like a iwwx/calL If st_mask is NULL, the call automatically resers 
BAD and OOS if a successful value set is performed. 
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st_only 



a?pl_work 



Return Codes: 
0M_SUCCSS5 
ZSADTYPE 



If sc_only is TRUE (non-zero), only a scacus se: is performed. The iara 
value is noc se:. If sc.only is TRUE and sc_mask is NULL, die call is a 
NOP. 

A pointer co a workstation ID string. For application programs, spe-ify 
OM_APPLICATION (defined in om.udef.h). " 



The ser request has been initiaced successfully. 
The specified daca type is noc supported. 

The specified data type does noc march che actual daca cype (shared vari- 
ables only). 

For ALIAS, che daca cype is noc STRING. 

For shared VARIABLE daca cype OM_BOOL, specified value is noc 1 
(True) or 0 (False), 

Object name coo long. - 

Process variable name wich object cype noc equal co VARIABLE. 

For STRING daca cype, specified string Icngch coo long or < = 0. 

For STRING daca cype, specified string lengch longer chan actual serine 
length. 

Objecc cype DEVICE or PROCESS was specified. 
Variable is secured. See Nocc 3- 
Shared variable value record bad. 
Object noc found. 

Object noc found in specified scation. A station is specified by imporc cable 
entry, PSAP paramcccr, or list ID and index parameters. ENOTFOUND 
occurs when the object is on the imporc Use, buc che scation lisccd as in 
home cannot find it. This means chac che object" has probably been moved 
to anochcr station. 

Caller noc activaced wich IPC. 

System resource availabiiicy problem. 

IPC recurned an unspecified error. 

Invalid bits set in write scatus mask. Valid bics are denned in 
OM_UDEF.H. 

Workstation ID name invalid lengch (muse be exactly 13 characters). 
Return Code Noces: 

1. OM error codes arc negative (refer co OM_ECODE.H or Appendix B). 

2. Control and I/O (compound processor) recurns positive error codes (refer to the 
document System Messages), 

3. These error cases are returned only if the variable is local. 



E3ADNAME 



ESTRLEN 



ENO VALUE 

ESECURH 

E3ADVREC 

ENOCONFIRM 

ENOTFOUND 



KfOT ACTIVE 
ENOSPACS 
EIPCRET 
ESAOMSK 

E2ADWXSTA 
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Call Notes: 

1. Placing a local object (one found in chc same starion) on che import list is unneces- 
sary, so for local objects st_setc7ifignotcs that oprion. 

2- For process control variables, BAD and OOS arc always cleared before che masked 
status write is performed. 



\ 
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' anObjia 115 - 60 ^"'" 1 " Va ' Ue and/ ° r Status of 

itjudist_amfirm sets the value and/or die scacuKjf die soedfled object This call i. , C 

cf Ir a T f0biKtSIlmS bi ° - bc! « onlrpaxame^alb^tlriL 

I ^ abfa " t r " KC °™™ d » ^ ™» *>, shared variab eT 

I vanables, and abases, lyribtajj, ia synchronous; it initiates the SETVAL messL Z 

wait, for a resporae before returning control to your process/task. ^ 

Fonnac 

I ^f! £ 7 Satlisfc - COnfir3l(<riame> ' <cfa 3-ty?e>, <import>, <value> < SCa tu s > 

I <data_len>, < 0 pen_id>, <ov_inde*>. < St _daca>, < sC _ maste > < <n!^2Sb«*>J 

1 Char *naaie, *valua,. -ap?l_wcrk; 

itlC obj.type, imporc. caca_len. open_ic, 'ov index- 

unsigned int -status, sc.data. s=_mask. st_cnly ; 



Where: 
*name 

°bj_type 
import 

•value 

•status 



<2ata_len 

open_id 

ov_index 

st_dat:a 

st_mask 



A pointer to the name of the object. 

The named objects type; ei cher VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 = Do not place the objects name on the import list. 

A pointer to the values location. Specif/ its size in bytes using data_len if 
it is a string or process variable. 

A pointer to the location where you have stored the objects dara type 
(range 1-15). 

An ALIAS object type can only have STRING data type 
The shared VARIABLE object type can have a data, type of CHARAC 
. TER, INTEGER, FLOAT, STRING, OM.BOOL (byte with True/False 
values only), OM.LNGJNT (long integer), OM_S J>KBOL (short 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager does. not restrict process VARIABLE data types. All 
shared VARIABLE data cypes are supported plus CIO.SHORT (unsigned 
character). 

The length (in bytes) allocated for "value". This is needed for STRING 
data types and all process variables (0 defaults co size of float). 
ID of open variables list that concains che variable to sec. 
Index of a variable en cry within the list. 

Object scacus daca bits. This word specifies che desired seccing for che bics 
specified in st.mask. Only bics defined in om_udef.h (BAD, OOS, and for 
process concrol variables only ACK) are allowed co be sec/rescc. 

Object status mask bics. Bics sec in chis word specify che bics to set/ reset 
according to their setting in the data word. If st.mask is NULL, che call 
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sc_only 



appl_work 



Renirn Codes: 

OM.SUCCSSS 
E3ADTYPZ 



performs like a serjalcall If sc_mask is NULL, che call aucomaucallv resea 
BAD and OOS if a successful value sec is performed. 

If st_only is TRUE (non-zero), only a scacus sec is performed. The daca 
value is noc sec If sc.only is TRUE and sr.mask is NULL, die call U , 
NOP. 51 

Apoincer.co a workstadoh ID string. For applicadon programs sorT/ 
OM^APPUGATION (defined in om_udef.h). ' ~ ' 



The sec request has been iniriaced successfully. 
The specified daca cypc is noc supported. 

The specified daca cype does noc macch che accual daca cype (shared vari- 
ables only). 

For ALIAS, che daca type is noc STRING. 

For shared* VARIAB LE data cype OM_BOOL, specified value is noc 1 
(True) or 0 (False). 

Object name coo long. 

Process variable name with object type noc equal to VARIABLE. 
For STRING daca type, specified string length coo long or < = 0. 

For STRING daca cype, specified string length longer than actual string 
length- 
Object cype DEVICE or PROCESS was specified. 
Variable is secured. 
Shared variable value record bail 
Object not found. 

Object not found in specified station. A station is specified by import cable 
entry, PSAP parameter, or list ID and index parameters. 

Caller not activated with IPC 

System resource availability problem. 

IPC returned an unspecified error. 

Specified list noc open. 

Specified index greacer chan size of lisc. Specified index entry noc con- 
nected. 

Invalid bits set in w^ice scacus mask. Valid bics arc defined in om_udef.fi. 
Wbrbcarion ID name invalid lengch (muse be exacdy 13 characters). 
Return Code Notes: 

1. OM error codes are negative (refer co OiVLECODE.H or Appendix B). 



ESADNAME 



ESTRLEN 



ENOVALUE 

ESECORS 

E3ADVREC 

ENOCONFIRM 

ENOTFOUND 

ENOTACTIVE 
ENOSPACE 
EIPCRET 
ENOTOPENED 
EB AO INDEX 

E3ADMSX 
E3ADWKSTA 
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2. Control and I/O (compound processor) returns positive error codes (refer to the 
document System Masages) . 

3. If a value is successfully set, its BAD and OOS status bits are automatically reset 
Call Notes: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects st_sediscjconfirm ignores that op don. 

2. For process control variables. BAD and OOS are always cleared before the masked 
status write is performed. 



I 2.14 st_setjist- Set the Value and/or Status of an 
Object 

^Jrrrsccs che value and/or the status of the specified object. This call is a functional extra 
sion of the setvdJistcaH. A status mask and a scatus data parameter allow the specification of 
object status bits to be set or reset. A status only parameter allows che writing of status wither 
am accompanying data value. This call works for shared variables, process Variables, and 
aW st_serjzstis asynchronous if the object is not in the local station; it initiates the SET- 
• VAL message and returns control to your process/task. 
Formac 

int «tJ«t_li«e<<n«M>.<obj_eyp«^ ' e -> 
<cpen.id>,<ov_incex> / <sc_data> # <s.t - mask> / <st_only>,<appi_ work>) ~~ ~ ' 

char *name, 'value *appl_work; 

lnt ■ obj_type, import, data_len, open_ic, ov.index; 

unsigned int 'status, st_data, st_mask; st.only; ■ 



♦Where: 
*narne 
°oj_type 
import 

*value 

* status 



data_len 

open_id 

ov_index 

st_data 

st_mask 



A poin ter to the name of the object. 

The named objects type; either VARIABLE or ALIAS. 

1 = Place the objects name on the import list. 

0 ■« Do fcot place the objects name on the import list. 

A pointer to the values location. Specify its size in bytes using dataller, if 
it is a string or process variable. 

- A pointer to the location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING data type. 
The shared VARIABLE object type can have a data type of CHARAC- 
TER, INTEGER, FLOAT, STRING, OMJOOL (byte with True/False 
valu« only), OM JJ^G JNT (long integer), OM_S_PKBOL (short 
packed boolean), or OM _LJ>KBOL (long packed boolean). 
The Object Manager does not restrict process VARIABLE data types. All 
shared VARIABLE data types arc supported plus CIO_SHORT (unsigned 
character). 

The length (in bytes) allocated for "value." This is needed for STRING 
data types and all process variables (0 defaults co size of float). 

ID of open variables list chac contains che variable to sec. 

Index of a variable entry within the list. 

Object status daca bits. This word specifies che desired sectine for the bits 
specified in st.mask. Only bics defined in om_udef.h (BAD, OOS, and for 
process control variables only ACK) are allowed co be sec/resec. 

Object status mask bics. Bics sec in chis word specify che bits co sec/rese: 
according to cheir seccing in che daca word. If sc_mask is NULL, che call 



Section 2. C Oils to Cet/5et Object Vafues 



*P»0 EV 32484940 4US 



■r 



i ) 



B01938C- October 31, 1995 



sC_only 

appl_work 

Return Codes: 
OM_SUCC£SS 
EBADTYPE. 



RYn^^cT^ 1 - rf /y-T k 15 NULL tKc ^ auco ^all y resecs 
oAJJ and OOS if a succcssrui value sec is performed. 

If sc__oniy is TRUE (non-zero), only a scacus se: is performed. The daca 
vake is noc sec. If sc_o'nly is TRUE and sc.mask: is NULL, che call is a 

Apoincer co a workscacion ID scring. For applicacion programs, sDe-ifr 
OM_APPLICATION (defined in om.udef.h). ° P * 



The set request has been initiated successfully. 
The specified daca cype is noc supported. 

The'specified daca type does noc macch the accual daca type (shared vari- 
ables only). See Noce 3. 

For ALIAS, the daca eype is noc STRING. 

For shared VARIABLE data type OM.BOOL, soecified value is noc 1 
(True) or 0 (False). Sec Noce 3. 

Object name too long. 

Process variable name with object cype noc equal to VARIABLE. 

For STRING daca cype, specified string length coo long or < = 0. 

For STRING daca cype, specified scring length longer than actual serin* 
length. See Noce 3. ° 

Object cype DEVICE or PROCESS was specified. 

VARIABLE is secured. See Noce 3. 

Shared variable value record bad. See Note 3. 

Specified list noc open. 

Specified index greacer chan size of list. Specified index entry noc con- 
nected. " 

Invalid bits set in write scacus mask. Valid bics are defined in om_udef.h. 
Workstation ID name invalid length (must be exactly 13 characters). 
Return Code Notes: 

1. OM error codes are negative (refer co OMJECODE.H or Appendix B). 

2. Concrol and I/O (compound processor) recurns posicive error codes (refer co che 
document System Messages) . 

3. These error cases are recurned only if che variable is local 
Call Noces: 

1. Placing a local object (one found in che same stacion) on che import lisc is unneces- 
sary, so for local objeccs st_se:Jist ignores chac option. 



Z3ADNAMZ 



SSTRLZN 



ENOVALUE 
BSECOSffi 
E3ADVRZC 
ENOTQPEMED 
EBAD INDEX 

23ADMSX 
E3A0WX5TA 
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2. For process concrol variable, BAD and OOS arc always cleared. before che masked 
scacus write is performed. 



Section 2. C Calls to Cei/Set Object Vai 



es 



n EV 3*2484940 408 

B01938C- October 31, 1995 



| 2.1 5 st_setval - Set the Value and/or Status of an 
Object 

stjetvalstxs che value and/or che scacus of che specified objecr. This call is a functional exten- 
sion of che setval call. A status mask and a status data parameter allow che specification of 
object status bics co be set or reset. A scacus_only parameter allows che writing of status with- 
out an accompanying data value. This call works for shared variables, process\ariabies f and 
aliases, st^servalh asynchronous if che object is noc in che local station; ic initiates the ' 
SETVAL message and returns control co your process/cask. 
Formac _ 

inc st_setval (<naiae>, <obj_eyp«>, <inqporfc>, <value>, <«c*Cus>.<data i en> 
<sc_data>,<sc_mask> # <sc_only>,<appl_work» 

cixar *nane, w value, *acpl_work; 

xnt osj_type, inport, data_len; 

unsigned int ^status, st^data, st_mask, st_only; 



Where: 
•name 
obj_type 
iznporc 

*value 

^status 



« clata_len 
sc_data 

st_mask 



A poincer co che name of che object. 

The named objects type; eicher VARIABLE or ALIAS. 

1 = Place the objeccs name on che import list. 

0 = Do noc place che objects name on the imporc list. 

A poincer co che values location. Specify its size in bytes ustne cata_len if 
it is a string or process variable. 

A poincer co che location where you have stored the objects data type 
(range 1-15). 

An ALIAS object type can only have STRING daca type. 
The shared VARIABLE object type can have a- data type of CHARAC- 
TER, INTEGER, FLOAT/STRING, OM.BOOL (byre wich True/False 
values only), OM_LNG_INT (long inreger), OM_SJ>KBOL (shore 
packed boolean), or OM_L_PKBOL (long packed boolean). 
The Object Manager docs noc resrricr process VARIABLE daca cypes. All 
shared VARIABLE daca cypes are supported plus CIO_SHORT (unsigned 
character). ' 

The length (in byres) allocared for "value." This is needed for STRING 
daca types and all process variables (0 defaults co size of float). 

Object status data bits. This word specifies che desired setting for the bits 
specified in sc_mask. Only bics defined in om_udef.h (BAD, OOS, and for 
process concrol variables only ACK) are allowed co be sec/reset. 

Objecr scacus mask bics. Bics sec in this worked specify che bics co sec/ reset 
according co cheir setting in the daca word. If sc_mask is NULL, che call 
performs like a se&al call If sr_mask is NULL, the call automatically resets 
BAD and OOS if a successful value set is performed. 



stLonly If st_onIy is TRUE (non-zero), only a status sec is performed. The data 

value is noc sec If sc_on!y is TRUE and st_masfe is NULL, the call is a 
NOP. 

appLwork A poincer co a workstation ID string. For aoplicarion programs sDe-ifV 

OM^AP PLICATION (defined in om_udef.h). 



Return Codes: 

OM_SUCCESS 
E3ADTYPE 



The set request has been initiated successfully. 
The specified daca cype is noc supported. 

The specified daca cype does noc match che actual data cype (shared vari- 
ables only). Sec Noce 3. 

For ALIAS, the data cype is noc STRING. 

For shared VARIABLE data cype OM_BOOL, specified value is not 1 
(True) or 0 (False). See Note 3. 

Object name too long. 

Process variable name with object type no t equal to VARIABLE. 

For STRING daca cype, specified string length too long or < = 0. 

For STRING data type, specified string length longer than actual string 
length. Sec Note 3. 

Object typeDEVICE or PROCESS was specified. 
VARIABLE is secured. See Note 3- 
Shared variable value record bad. Sec Note 3. 

Invalid bits set in write status mask. Valid bits are defined in om_udef.h. 
Workstation ID name invalid length (must be exacdy 13 characters). 
Return Code Notes: . . - • 

1. OM error codes are negative (refer co OMJECODE.H or Appendix B). 

2. Compound I/O (compound processor) returns positive error codes (refer to the 
document Sys^ Messages). ~ * 

3. These error cases are returned only if che variable is local. 
Call Notes: 

1- Since this. call is asynchronous, ic cannoc waic for return codes from remoce sea- - 
tions. Thus all recurns concerning the object co be sec can only come from che 
local station. Control variables can only be local in a Personal Workstation (a PC 
PW-C or PW-FB). 

2. Placing a local object (one found in che same scacion) on the imporc Use is unneces- 
sary, so for local objects stjsetval ignores chac opdon. 

3. For process concrol variables, BAD and OOS are always cleared before che masked 
status write is performed. 



E3ADNAME 



ESTRLEN 



ENOV&LUE 

ES2CURE 

E3ADVREC 

E3ADMSX 

ESADWKSTA 
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3. C Ca//s to Access/Update Sets of 
Variables 



These calls allow your cask co establish lists of process variables (using omopen) with values 
uidxcanng how much change has to take place in che variables value before your cask is nod- 
hed (by dqchonge). 

Copies.of the values and status of the variables in an opened Use are maincained locally so that 
the response on reads is immediate and requires no additional network traffic. These calls are 
designed for casks needing ongoing access co many proce ss vari ables. 

A cask can read from or wrice co variables on a list returned by omopen until you issue an 
omdose. At that time (for optimized lists) che Object Manager returns a cable of addresses 
where it found the variables. " 

Subsequent omopens can use dw same table of addresses, thus saving processing dme. 

The OM Ccalls co access/update sets of variables are listed in this Section in alphabetical 
order and summarized in Table 3-1. 



Table 3-1. C Calls to Access/Update Sets of Variables 



Paragraph 
No. 


Call 


Function 


3.1 


dqchange 


Check foe objecr value changes 


3.2 


dqlist 


Dequeue open variables list ; 


33 


omdose 


Close che specified variable list 


3A 


omopea 


Open a sec of variables 


3,5 


omread 


Read values from opened list • 


3.6 


orawrice 


Write values to opened list 


37 


omwrscac 


Wrice values and/or status co opened list 
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3.1 dqchange - Check for Object Value Changes 
3.1-1 dqchange call 

This call dequeues the notification of change in a variable lis: which the specified process has 
opened (with (rmopen). The list is enqueued when a change-driven event occurs to a variable 
within the list, and the list is not already in the change queue. The updated information is 
also copied into the list. In order to register as a change, the change has to be greater than or 
equal to the delta_value (in the omcpen call) or the status has to change. To be notified, set the 
NOTIFY option in the list at omopen time. If the NOTIFY flag is set, the header node for the 
open variables list is linked to the end of a change notification queue, and the change notifica- 
tion message is posted to the mailbox for that queue. Change queues are created and managed 
by the Object Manager on a per process basis. Change notification for a given list is placed on 
the queue for the process that opened die list. The dqchangd) caller specifies a process ID, and 
therefore identifies a particular change queue. 
Format: - 

int dqchange (<pid>, <suscend>, <ccen_id>, <size_lisc>, <valua_list> 
<ret_size>) — 

int pid / suspend, size_lisc; 

int *open_id, *ret_size; 

struct ..value *value_list; 



Where: 
pid 

suspend 
MX' *open_id 
size_list 
*value_list 

*ret_size 



The process id number of the process that opened the target list. 

1 • Suspend execution until a change comes in. 

0 m Do not suspend; if no changes, return code = EQEMPTY. 

A pointer to the integer location that will receive the open_id which tells 
you the first variable list that was found to have changes. 

The number of elements in the value structures array that you have created 
to receive the changed values. 

A pointer to the caller-supplied array of structures. Each new/changed 
value is returned in one of the array element structures. The array of 
"value" structures is described below. 

A pointer to the location where the Object Manager returns the number of 
changed variables recurned. 

struct value ( 

ir.c index; 
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} aval; 
} values C ] ; 



index 



status 



The index value inco che variable list corresponding co che 
variable chac changed. 

The data type and stacus of che variable chac changed: 



Return Codes: 

OM^SUCCESS 
ESECURZ 

ENOTOPENED 

EC0NN3AD 
EQNOTEMPTY 
EQEMPTY 
0M_EC3SY 



0 ■ This value noc read yet. check for error 

Daca type — Low byte, btcs 0 co 4 

1 * CHARACTER 5 = BOOL 

2 = INTEGER 6 * OiM.LNGJNT or POINTER 

3 « FLOAT or REAL " 9 « OiMJ>ACKED_BOOL 

4 = STRING 10 - OMJXDNG J>ACKED_BOOL 

Error scacus — Low byte, bics 5 co 7 

0 « No response 4 * Bad daca type (scring) 

1 = Being scanned or unconneccable compound 

2 m Disconnecced 5-6 s (noc used) 

3 = Deleted. 7 = noc seac (error returned) 

uval The acrual value of che variable. 

ret_size Number of clemencs recurned. 

Changed variables have been successfully returned. 

The o mop en specified wrice access and actempced co connecc co a variable 
which had been previously secured for wrice access. None of che variables 
are connected. The caller should perform an omclose co close che Use 

The specified process id did noc perform any omopens which resulced in 
leaving a list opened, or che omopen did noc specify any variables for noci- 
ficarion access. 

The omopen could noc establish an IPC connection because no connec- 
tions were left. You should close che list using che omclose. 

The structure a var" array, supplied by che user, is coo small co hold all che 
changes chac che Object Manager has in ics queue. 

You did noc specify che suspend opcion and che queue does noc contain che 
specified lisc. 

Connection was busy on at least one station. The others are opened. There 
is no auto-reconnect. 



Call Notes: 

L Each variable lisc is identified by the openjd returned when che list was opened. 



2. You can specify any task (processed) that has open lists. If more than one list has 
changes, dqchange returns those in the first list, then removes that list from its 
queue. Use another call to get the changes in the next list. 

3. There is a macro, v_variist(s), that statically or dynamically allocates the value 
structure for you. This macro is defined in the om_user.h include file: 

See fine v_varlisc(s) valloc (sizeof (struct valuaj's) 
1 he following is an example of how this macro could be used: 
si.2a_.list = 10; 
vaiue_lisi: = v_variist(10) ; 
if (value_list == (struct value *) NULL) 
{ 



} 



The Hist line sets the sizejist calling argument. The second Une dynamically allo- 
cates a 10-eleraent array of "value" structures. 

tfyou use this macro, be sure to free the memory when the structure is no longer 
needed. It is alsqadvisable to check that the macro did not return a NULL pointer 
• indicating insufficient available memory. 

4. A process id number is maintained by the operating system for every task. A task 
can retrieve its own process id number using the getpid command For more infor- 
mation on getpid(2) refer to the UNIX Progmmmer's Reference Manual You can 

a dqchange for me variable list ofsome other task, but since you can only use f~ 
getpid for your own task number, the other task has to have sent you its process id. ^ 

5. Be careful of specifying that this call suspend. If an omopen failed, and you 
dqchange with the suspend option, it suspends forever. Check your omopens to 
make sure they were successful. 

3.1 .2 Change Queues 

The Object Manager has the ability to search a queue, and to dequeue an element regardless 
.of its position within the queue. * c 

The Process/Queue Table is a high level data structure used to manage change queues. This is 
an array of change queue descriptors dynamically allocated by code, and pointed to by process 
queue tables. r 

A change queue descriptor contains the ID of the process or task for which the queue has been 
allocated. There is no more than one queue per ID, so the ID is passed to dqckangeQot aqlistO 
to identify a particular change queue. 

A process/task with at least one currently open list containing change driven variables has a 
change queue allocated for it. The queue descriptor contains the currcne number of change 
driven lists opened by che process. The queue descripcor is free and may be (refloated when 
the couric is zero. 
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The change queue is a singly linked FIFO queue of open variable list headers. Head and tail 
pointers are kept in the queue descriptor. The headjtr member points to the first list header 
m the queue, and the taiijtr member points to the NULL pointer that terminates the 
linked queue. If the queue is empty, the head_ptr contains NULL, and the tail j;- points 
to the head__pcr. "~ ^ 

A list header is added to the tail of the queue by storing a pointer to the list header at the loca- 
tion indicated by taiutr. Then tail_ptr is changed to point into the list header, to the 
NULL pointer terminating the queue. 

When dqckangtQ removes a list header from the queue, it is the header to which head_per 
points. When dqtist removes a'header, it is a header that may have been found anywhere 
within the queue. The header is removed from the queue and pointers are updated. If remov- 
ing the header leaves the queue empty, the tail jtr must be updated to point to headjtr. 
The UNIX semaphore in a change queue descriptor is for use with the system calls. When a 
queue is empty and the dqchangft caller wishes to suspend until the next change notification, 
it is accomplished using a system call that specifies "the semaphore associated in the queue 
descripcor. When a change occurs, notification is accomplished using a matching call. 
TherfollQwing diagram shows the change queue hierarchy. There are three change queue 
descriptors ; in use. This means that there are three processes with open lists of change driven 
^^J^- 0ne of die queues is emp ty. For two of the processes, changes to lists have occurred* 
but have jiot yet been seen by the application. 
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proc,que_tbl 

change queue descriptors 



i PID 


PID 




PID 






cnt>=1 


cnt>0 


cnt > 0 


cnt >=2 


cnt = 0 




head pt 


head pt 




head pt 






tail pt 


tail pt 




tailpt 






semiphr 


ssmiphr 




samiphr 








header_node 



vars list 



vars list 



cnt = 0 




headerjiode 



vars list 
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| 3.2 dqlist- Dequeue Open Variables List 

This call dequeues che notification of change within che specified open variables lisc. The list 
is enqueued when a change driven event occurs to a variable within the list, and the list is not 
already in che change queue. The updated information is copied into che lisc. 
Like dqchange, dqlist specifies a process ID, and therefore identifies a particular change queue 
The list must have been opened by the specified process. No change notifications can be 
found otherwise. When this call is made, the Object Manager checks the change queue associ- 
ated wtcn the specified process ID for che change notification for the specified list. If the lisc is 
noc in che change queue chan che call cecums eqe*pty (whether or not che queue is actuallv 
empty). Once the change notification for the lisc is found in che change queue, ic is removed 
from che queue. The value lisc information is recurned co che caller, and che dqliszQ call 
recurns om_succ2ss. . 

Format: 

.inc <2qlist(<pid>,<suspead> # <open_id>,<size_iist>,<value_list>,<rec_size» 
inc pid, suspend, . size_list; 

iac *opea_id, *ret_size7 

struct value *value_list; 



"Where: 
pid 

suspend - 

size_list 

*open_id 

*value_list 
*ret_size 



The process id number of che process chac opened the career lisc 

0 - Must be a zero, CcvvoT 

The number of elements in the values array. 

Inceger ID of che target list. The ID is obcained from the previous omopen 
call The list muse currendy be open. 

A pointer to the caller-supplied array of structures. Each new/changed 
value is returned in one of the array elemenc structures. The array of 
"value 11 structures is described below. 

A pointer to an inceger which receives che number of array elements con^ 
taining returned variables. . 



struct value { 
int 
int 
union 



index; 

status; 

var_val { 
char 
int 
float 



letter; 
wcrd; 
f point ; 



} uval; 
} values ( ); 



index 



The index value inco che variable lisc corresponding co ch< 



variable chac changed. 
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status 



The daca cype and status of che variable chac changed: 



0 = This value noc read yet, check for error 

Daca type - Low byte, bits 0 co 4 

1 = CHARACTER 5 = BOOL * 

2 = INTEGER 6 = OM_LNG JNT or POINTER 

3 - FLOAT or REAL 9 * OM .PACKED JOOL 

4 « STRING 10 = OM_LONG_PACKED_BOOL 

Error Scacus —Low byte, bits 5 co 7 
0 = No response 4 ■ Bad daca cypc (scring) 

1 .» Being scanned or unconneccable compound 

2 * Disconnected 5-6 = (noc used) 

3 = Deleted 7 ■ noc senc (error returned 

uval The acruai value of the variable. 

ret_size Number of elements returned. 



Return Codes: 
CM_StJCCZSS 
ESECORE 

ENOTOPENZD 

ECONNBAD 



Changed variables, have been successfully returned. 

The omopen specified write access and actcmpced co connect to a variable 
which had been previously secured for write access. None of che variables 
are connected. The caller should perform an omclosc co close che list. 

The specified process id did noc perform any omopens which resulted in 
leaving a list opened, or the omopen did not specify any variables for noti- 
fication access. 

The omopen could not establish an IPC connection because no connections 
were left. You should close die list using the omdose. 

EQNOTEMPTY The structure "var* array, supplied by the user, is too small to hold all the 
changes that the Object Manager has in its queue. 

EQEMPTY You did not specify the suspend option and the queue does not contain 

the specified list. 

Call Notes: 

L Each variable list is identified by the open_id returned when che list was opened. 

2. There is a macro, v_varlist(s), chac stacically or dynamically allocates che value 
structure for you. This macro is defined in che om_user.h include file: 

Scefine v_varlist(s) valloc (sizaoc (struc- value) ^s) 
The following is an example of how this macro could be used: 

size_list = 10; 

value_list = v_varlisc (10 ) ; 

if (value_list == (struct value ') NULL) 
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} 



The first line sets the sizejisc calling argument. The second line dynamically alio- ' 
cates a 10-element array of "value" structures. 

If you use this macro, be sure to free the memory when the structure is no longer 
needed. It is also advisable to check that the macro did not return a NULL pointer 
indicating insufficient available memory: 

3. A process id number is maintained by the operating system for every cask. A task 
can retrieve its own process id number using the gecpid command. For more infor- 
mation on getpid(2) refer to the UNIX Programmer Reference MantutL You can 
issue a dqlist for the variable list of some other task, but since you can only use »«- 

^ pid^for yo4tt-ewn task number, the other cask has to have sent you ics process id. 

*\B^carefui of specifying chat chis call suspend. If an omopen railed, and you dqUst 
3*ch che suspend option - 1, it suspends forever. Check your omopens co make 
/sure chey were successful. 
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3.3" omclose - Close the Specified Variable List 

This call doses a list of local or remote variables by releasing che connection established with 
the omopen call. It also supplies ail of the header information, variable list, and address table 
to speed up future omopen calls to the same list. 

omclose is asynchronous; it initiates the request then immediately returns control to your task. 
Format: 

int omclose {<open_id>, <header>, <var_list>, <addr_tbi>) 

open_id; 

struct otOieader_ncde w header; 
struct open_yar *var_li$t; 
struct net^addr • *acdr_tbl; 



mere: 




openlid 


The id number returned from the omopen call. 


*header 


A pointer to the ora_header_node structure. 


*var_list 


A pointer to the value structures array 


•addr_tbl 


A pointer to the address table for the list. 


Return Codes: 




OM_SUCCES5 


The request has been initiated. 


ENOTOPEND 


There is no open list corresponding to this open_id. 


SNOTACTIVE 


Not registered with IPC for connectionless service. 


EIPCRST 


You have an unspecified IPC error other than enotactivz. 


Call Notes: * 





1- The header node and variable list (and address table, if optimized) are returned so 
you can specify them che next rime you open this list. When the Object Manager 
is passed an optimized list with a network address table, it can open the list much 
more quickly 

• 2. Do not modify the optimized list structures if the list is to be opened again at a 
later rime. 

3. It is imperative thac the lists be closed before any exit from the program. 
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3.4 omopen - Open a Set of Variables 

This call opens a list of up co 255 locaJ or remote variables, omopen operates on a list of local 
and/or remote variables, creating a set of connections to the variables. These connections 
must be made before any data access can be done on the set o f variables using the list. There- 
fore, you must use this call before using any of the other list access calls. There are both opti- 
mized and unoptimized versions of omopen. This call is asynchronous for local variables: it 
uuaatcs the request and then immediately returns control to your cask. This call is synchro- 
nous for remote variables; you must wait until the transmission of remote open messages is 
complete. 

Format: 

int oraopen(<om_descriptor>,<open_id>) 

struct om_header_node ~ca_descriptor; 
int *open_id; 

Where: ~ 



*om_descrip tor A pointer to the header_aoce data structure, described in paragraph 3.4.1 , 
Optimized and Unopdmized omopen calls. 

A pointer to the locadon where the Object Manager returns the list num- 
ber. 



*open_id 

Return Codes: 
OM — SUCCESS 
EBADRSZ 

ENOACTIVE 

ENOTFOUND 

ENOQUE 

EOMOSIZE 

ESZCtJRI 

ENOSPACE 
EOPENED 
E3 AD LIST 
EC0NN3AD 



The list has been opened. 

For an optimized list, being opened the firsr time, the current size of the 
Network Address Table is not zero. The list is not opened. 

Call not registered with IPC for connectionless communications. List is 
opened, but remote variables not being scanned. 

One or more variables can't be found; the rest are being scanned (unopd- 
mized version only) 

The list specified change notification and there are no change queues avail- 
able. The list ts not opened. 

The size of the open variable list exceeds the maximum. The list is not 
opened. 

A connection was attempted to a variable which has previously been con- 
nected for write access. If this error is returned, none of the variables in the 
list are connected. The list is opened but not available for write access. 

There is not enough room in memory to open a list, try again later. 

The list is already opened. 

The variable list pointer is NULL. The list is noc opened. 
List open but noc connected, no write access.. 
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ENOADDTBL List is marked as having been optimized. There is a NULL poincer inste ad 

of a Network Address. Table. The list is no c opened. 

EDfOSEND Not enough space to allocate message buffers. List is open, but remotes are 

not connected or scanned, local variables are being scanned. 

ENCADRS? You specified a Network Address Table that is too small. The list is open 

but none of the remote variables are being scanned. Variables that fit in the 
table are being scanned (optimized version only). 

EHAXOPNS The omopen id table is full (maximum number of opens reached); list not 

opened. 

ESCANFvJL List open, but the local scanner database is full; variables that fit in the 

database are being scanned. 

EIPCRZT ^ You have an unspecified IPC error, other than ENOTACTTVE 

Call Notes: 

1. Names in the open list should be uppercase to ensure reconnection. All the speci- 
fied variables are scanned,* at the scan jate, for changes greater than or equal to the 
delta value. Those that change can be picked up with a dqchange or omread. 

2. The unoprimized version of this call saves space by using the OM s address table. 
Your variable addresses are found and added each time you open the list. 

3. Use the open_id to issue the omdose call It is imperative that the lists be closed 
before any exit from the program. 

4. Optimized is fester, but takes up more memory; unoprimized is slower but uses 
less memory. The first omopen is always unoprimized (since it has to find the net- 
work addresses). 

5* For lists with write access only, specify NO_NOTTFY and a large delta. This saves 
the overhead of unnecessary data reading, and saves a change queue. 

3-4.1 Optimized and Unoptimized omopen calls 

Whether an omopen call is optimized or unoptimized depends on whether the network 
address cable_poiriter (in the om_header_node structure) is null or not. For the faster, opti- 
mized operation you have to provide a Network Address Table in addition to the 
ora_header_node and a list of all the variables you will want to access. 

A list which docs not have its own Network Address Tabic is not optimizable. The 
oiOieader_node contains a NULL pointer instead of a pointer to an address table. When the 
list is opened, there is no information showing where on the network the variables should be 
found. Those not found locally will be sought and opened via a broadcast message. Because 
the list docs not have its own address able, the returned network addresses are temporarily 
recorded in the Object Managers address able as long as the list is open. (The OM s address 
table is used by multiple functions within the local sation. The advantage is that no duplicate 
PSAP s need to be stored within the local sation.) When the list is closed, the location infor- 
mation is discarded. 
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To prepare a list for optimization (in anticipation of repeated oTnopatO calls), you muse allo- 
cacc memory for che address cable in dxe callers daca space. The cable may initially conrain 
garbage. The pointer co che cable, along with che current (zero) and maximum size values, is 
placed in che ora_header_noca. The firsc time che list is opened, the locations of ics variables 
are noc known. Those chac are found locally, and chose chac are found via che broadcast will 
have their corresponding PSAP s recorded in che Network Address Table belonging co che Use. 
The list is chen considered co be optimized. However, ic is only partially optimized if any vari- 
able was noc found by che rime che list is closed. The available location information is pre- 
served by che address table (and variable list). The nexc rime the lisc is opened, this 
information is used co avoid broadcasting, and makes che processing considerably fester. 

The relationships between che structures of open variable lists, both unoptimizable and opti- 
mizable, are shown below. 4 



*om_descriptor 




OPTIMIZED: 
For each ompen, supply the 
variable list. During the first 
omopen Object Manager will 
find the network address for 
each variable and build the table. 



variable 
list 



network 
address 
table 



When you call omclase, che Object Manager updates the information in the address table, vari- 
able list and header node. Save this daca, and the next time you omopen this list, supply all 
three to gready speed up che call. (Do noc change any of chem!) 

For unoprimized operation, which cakes up less memory, you just provide header node and a 
Use of variables. The Object Manager will use its own address cable. Create che lisc structure as 
follows: 



*om_descriptor 



1 


• 

omjieader.node 


network address pointer 









UNOPTIMZED: 






When omopen see this data 


variable 
list 


(NULL) 


structure it will use its 




own address table. 
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3.4.2 omopen User Initialization 

Before calling omopenQ, you must be a registered user and activated with IPC for connection- 
less communication.Thc daca structures associaced with a list muse be allocated and initialized 
before the list can be opened. 

The following definitions statically allocate space for an csL-headar.ncca, a variahia_list 
and a Network Address Tabic, A list with ten elements permits connections to that many vari- 
ables. A list may contain up to 255 elements or variable address entries. The maximum size 
(five elements in the example shown below) is based on the number of stations (local and 
remote) in which any of the listed variables may be found. These structure definitions are 
defined when the user includes cm_usar.h. 

The following C code fragments are examples of how you can set up your data structures: 

^include <om_user.h> 
main () 
{ 

static struct om_haader_node ora_descriptor; 

static* struct o?en_var variabie_lise(10] ; 

static struct net_adr net_acr_tbl [5] ; 

static int cpen-id; 

The above example statically allocates a variable list of 10 elements (Le., you wish to connect 
| to 10 variables). It also allocates a header node and a Network Address Table for five entries. 

The C code below initializes the list header node. This is an optimizable list, since the pointer 
i to a Network Address Table, rather than a Null Pointer, is stored in the net_adr_tbl_ptr 
* ° member of the header node. The address table is empty, as iridicatedby the current size of 

* zero, but can hold up to the specified maximum number of address entries. 

Hie variable list structure is also linked to the header node- The current and maximum sizes 
of a list are the same unless there are unused entries at the end of the list. Such entries would 
used with the unoprimized lists. A maximum size of zero is logically equivalent to the speci- 
fied current size. 

List state information is kept in the header node. The list has an access mode of read-only, 
write-only, or read/write. The access mode codes are defined in ora_user .h and one code 
must be placed in the task_stacus member of die header node. 
' The htskst_o pm (optimization change flag) bit of the task status member must be initialized 
to zero to show that the list is not optimized. (This is accomplished below in the process of 
storing om_r_accsss.) 

The scanner update frequency is specified in the list header. The 16-bit scan rate member of 
the header node is divided into a scan delay high byte and a scan race low byte. The scan delay 
byte contains the number of half-seconds between the first and second scanner updates. The 
scan rate byte contains the number of half-seconds between updates thereafter. A scan delay of 
zero means that all scanner updates will occur at the specified scan rate. 




- P rP Ey5 24649A0 4US 

f f ) 



Section 3. C CaUs t0 Access/Update Sfifs o(v ^ ^ ^ ^ ^ 

S«t C tc d A™ " d I' 165 " f C h " dCr " C ^ ^ ** Man ^ »d must be 

set co zero. Among these arc bits in die cask.stacus and status.ext. 

The following code example is for sctring up che scruoures: 

byta.fiu (& om_descriptor, 0, size of {strict om_heada- ncc» ) • 
™-cescriptor.task_status = OM_R_ACCZSS; " " ' 

^-descriptor. status_ext = 0; 

om^descripcor.scaa.rate = (0 « 8) . 3; 

ora -descriptor.open_list_ptr = variable.lisc; 

om_descri p tor.cur_size_open_lisC = 10; 
om_descriptor.ma:<_size_opan_list = 10; 
cra_descriptor.net_adr_tbi_ptr = net_adr_cbl ; 

om_descriptor.siza_net_adrJ.cbl ' - 5; 
tvcJr- 

is secsAdr_tbl_pcr co poinc co che network address cable. Nocice that as a result of the ' 
ensuing o^nopenoll the list becomes optimized, because net_adr_tbl_ptr is not NULL. 
Th« also > sec^a^pen.ust.ptr to point to the variable list, sets the maximum and current 

If vLlL. r^n*"?" ^ C ° 5 ^ °' rCS P ecdvc ^ nuudmum and current sizes 

oFvanable list to 10 and 10, and sets the access to read only. Acruallythe sizes can be any- 
dung you-wish. 7 

OM_r_access, ok_w_accZ5S, and om_rw_acc2S3 are all defined via the include file. 
The following code example is for setting up the variable Use 

strcpy (variable_list[0J .nana, name) ; 

variable_list(0].var_desc = NOTIFY ; 

variable_list[0]. delta - dalca_value; 

variable_list[0].var_stat = 0 

This example sets up the variable list just for element zero. You would have to set it up for all 
elements you want to connect to, but not necessarily all of the elements in the list. 
The Null-terminated variable name string is copied into the name member. Names should be 
encered in .uppercase. The NOTIFY opriorris specified in che var.desc member, and che 
change driven delta value is stored in the delta member. . 

The fouowing code opens the list. The list is specified using the address of the header node 
scructurc. The ID of the opened list is. returned, along with any resulting error code. 

result « craopen(&om_dascrip=:>r, &open_id) ; 
No fotther initialization is needed to reopen a list (optimized or not) after it is closed. 
Ic is essential that, aside from initialization, you do not alter these structures once the list has 
been opened, except through Object Manager calls. This is especially true for an optimized 
list, even when closed, if it may be opened again. 
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3-43 omopen Connections 

When a lisc containing optimized remote variables is opened, a connectionless send of a 
omopen message goes to each remote station believed to have some of the optimized variables. 
The message consists of one or more packets. A packet contains a copy of the list header as 
well as the list entries for as many variables as will fit in the packet. 

When a station receives an -omopen packet, the packet is processed by the server^ornopen rou- 
tine. This routine allocates, initializes, and opens a new list of the variables specified in the 
omopen packet- If the list has already been opened, the lisc is extended to contain the variables 
specified in this latest packet. The list already exists if the packet was not the first packet 
received for the omopen message. The list would also exist if an open broadcast message had 
already been received for the same list. 

The variables specified by the omopen packet are expected to be local to the st ation to which 
the packet is sent. The variables when located, arc added to the Scanner database, and secured 
if the list is used for write access. 

3.4.4 omopen Server Broadcast^ 

When a list containing unoptimized remote variables is opened, a connectionless broadcast of 
an omopen broadcast type message is issued. Thejnessage consists of one or more packets. 
Each packet contains a copy of die list header as well as the names and some information 
about as many of the non-local variables will fit in the packet. 

When a station receives an omopen broadcast packet, die packet is processed by the 
server_omopenjbcast routine. This routine allocates, initializes, and opens a new list of the 
variables specified in the broadcast omopen packet. If the list has already been opened, the list 
is extended to contain die variables specified in this latest packet. The list already costs if the 
packet was not the first packet received for the broadcast message. The list would also exist if 
an omopen message had already been received for die same list. The variables specified by the 
broadcast packet are searched for locally. The variables, when located, are added to the scanner 
database, and secured if the list is used for write access. 

A remote station knows when it has received all of the omopen and open broadcast messages 
for a particular list. The total numbers of optimized and unoptimized variables to expect are 
contained in every message packet. When enough message packets arc received to account for 
all of these variables, and when these packets have been processed, the remote list is consid- 
ered opened. - 

Once the remote copy of the list is complete, the remote station sends an open return type 
message back to the original station. This message indicates that the remote open has been 
completed, whether there were variables that were found, and whether the open failed. 
No remote list is created if the station does not have any of the variables represented in the 
message packets. If any omopen message packets (representing optimized variables) were 
received, the open return message is sent even if none of the optimized variables could be 
found. If a station receives only open broadcast message packets (representing unoptimized 
variables), and does not have any of the variables, it will not send an open return message. 
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3.4.5 omopen Server Return 

The server^omopen^return routine processes che omopen return message when it is received by 
the original station. The corresponding list is found- If che list is optimized, che key code from 
che remote station is compared against chat in che corresponding en cry in che Network 
Address Table entry. If the key code has changed, the optimization change bit is set, and the 
Nerwork Address Table is updated. 

Error status from the remote list is checked and incorporated into the status of the master 
(local) copy of the list. If there was an error, any relevant change-driven variables are flagged, 
and che list is posted to the change queue- 
Entry information needed from the remote list is copied into the master list. The count of sta- 
tions which have not yet responded to the omopen message is decremented, if appropriate. 
The count of unoptimized variables which have not yet been accounted for is also decre- 
mented, if appropriate. 

If che list has become optimized, che link open variables list is called to set up the network 
address links. 
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3.5 omread - Read Values From Opened list 

omread reads variables from die list ooened with che omoven call. This call allows you co read 
all or any part of che list. You can read pares of che list in any order This call is asynchronous. 
You muse check che seacus in che value structure co validate che data's integrity 
Format: 

i at omread ( <omopen_id> ,<siz e_l iso, <var_l iso} 
* nt omooen^id; 
int size_list; 
struct value *var_list; 



oraopen_id 
size_list 
w var_list 
value 



index 



status 



T he op en id returned by che omopen calL 

The number of value structures in che list. 

A pointer co che value array structure. 

An array of structures containing che following elemencs: 

struct value { 
int 

unsigned int 
union 



index; 
status; 
{ 

char 
int 
long 
float 



letter; 
word; 
longint; 
fpoir.c; 



} uval; 



}; 



The index value into the variable list corresponding to che variable chac 
changed. 

The data type and status of che variable that changed: 



0 = This value not read ycc, check for error 

Data type — bics 0 to 4: 

1 = CHARACTER 5 = BOOL 

2 = INTEGER 6 = OM.LNG JNT or POINTER 

3 = FLOAT or REAL 9 = OM_PACKED_BOOL 

4 = STRING 10 * OiVLLONG_.PACKED.BOOL 

Error scacus - bics 5 co 7: 

0 « No response 4 * Bad daca type (string 

1 = Being scanned or unconneccable compound 
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2 
3 



f Disco nneczed 
Deleted 



uval 

Return Codes: 

OM_SUCCESS 
ESECURE 

EMOTOPENED 
EREAD 

ECONNBAD 
ESCANFUL 

0M_EC3SY 

Call Notes: 



5-6 = (noc used) 
7 = Noc senc (error recurned) 

The actual value 0 f che variable. 



The list has been read. 

Attempt to open a secured variable. 

List is not opened (or bad om_dcscripcor). 

The omopen call was set for write only. 

Unable to connect co remoce scacion. 

Use open, local scanner dacabase coo small; variables chac fit in che dacabase 
are being scanned. 

Connection was busy on at lease one station. The others are opened There 
is no auto-reconnect. 



L For multiple errors, che return code shows only one. EREAD ERROR is suoer 
ceded by ESCANFUL, which is superceded by ECONNBAD. 

2. To only read part of the list, you can specify che order. If you read che whole lisc, ic 
rea.as in ascending order. 

3. If one of chc status values is zero, that variable has noc been read (or perhaps 
scanned) yet, or there is a problem such as bad data type or variable not found 
<~neck tor an error return. In any case, uval does not contain a legitimate value. 

4. If you wish to read all variables in che open lisc, macch sizejisc co che size of che 
open list. Do not set the individual indices. The Object Manager reads che lisc in 
ascending order of index number. 

5. There is a macro, v_varlist(s), thac statically or dynamically allocates the value 
structure for you. This macro is defined in che om.user.h include file as: 

* define v - varlist < s J vallocfsizaof (struct value) - S J 

The following is an example of how this macro could be used: 

size_list =10; 

value_lisc = v_varlist(10) ; 

if (value_list == (struct value ') KULL) 
{ 



The first line sees che sizejisc calling argumenc. The second line dynamically allo- 
cates a 10-elemenc array of "value" structures. If you use chis macro, be sure co free 
h m , Cm0ry whcn thc scru ccure is no longer needed. Ic is also advisable co check 
thac che macro did noc recurn a NULL pointer indicating insumcienc available 
memory. 
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3.6 omwrite - Write Values to Opened List 

amurrite wrices variables co the Use opened with che omopen call. This call allows writes to any 
or all entries in a list, omwrite is asynchronous if the variable is not in the local station; it ini- 
tiates the omwrite message and returns control to your process/ task. 

gesual can verify any omwrite regardless of the delta. If the write changes the value by che vari- 
able list delta, it can be verified by either of two ways: 

1. If che variable NOTIFY option is sec, use dqchange or dqlisv co verify che wrice. 

2. An omread issued after che list scan race period can also be used. 
Format: 

int omwrite (<omopen_id>, <siza_list>, <var_list>) ; 

orocpen_id, size_list; 
struct value *var_list; 

Where: 

cmopen_id The open_id recurned by che omopen call. 

size_list The number of value structures in che var_lisc 

* v ar_lis t A pointer to the struct value array. 

A value structure concains che following elements:. 

struct value { 
int 

unsigned int 
union 



index; 
status ; 
{ 

char 

int 

long 

unsigned int 
unsigned long 
float 



letters- 
word; 
longint ; 
uword; 
ulong; 
f point; 



} uval; 



} ; 



Where: 

index 

status 



uval 

Recurn Codes: 



The number (0 base) of the variable list encry co be wriccen. 

The daca cype of che variable (low order byte filled in by che caller). 
An error recurn code (next co low order byte): 

1 » Variable noc on scan 

2 = The user specified dan cype does noc macch che actual daca cype. 

3 = The index is <0 or grcacer than che size of che lisc. 

The value co be wriccen. 
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0M_SUCC2S5 

EN0SPAC2 

ENOTOPENED 

ESZCURE 

EWRITS 
OM_EC3SY 

ECONNBAD 



The list has been written. 
System resource availability problem. 

The specified list has not been opened successfully No writes are per- 
formed. ' 

The specified list has not been opened successfully because a variable in the 
list has been secured by another open list. No writes are performed. 
The list is opened for read-only access. No wrices are performed. 
The list was not opened successfully because one or more server stations 
have used up all its allotted IPC channels. No writes are performed. 

The list was not opened successfully due to one of the following 

1 . A remoce scanner data base is full. 

2. Optimized network address table is full. 

3. IPC send problems. 

No writes are performed. 

Not all remote variables in the list have been found/opened. No writes are 
performed 

The size of the write variable array is < = 0 or greater than the size of the 
open list. No writes are performed. 

An IPC error was encountered when sending an omwrite message to a 
remote server station. Variables may have been written to other stations 
For each variable in che write Iisc, validity checks are performed. If an error is encountered an 
error -code is set in the high byte of the caller's write list variable status. All variables are 
checked, even if an error condition is encountered in the loop. An FwAIT return has priority 
over EWRUERROR. If any error is encouncercd no wrices are performed. 
trfAlT A variable is not on scan. The (wrice list variable status) error code is set to 

I • 

The write list variable type (sec in stacus) does noc macch che open list vari- 
able type. The error code is set to 2. 

The write list variable index is greater rhan the size of the list (header 
cur_size_open_list). The error code is set to 3. 

A CP Wf ice error has occurred. Variables may have been wricten co other 
stations. The error code is set co 4. 



SSTATION 



SOMWSIZE 



23TOTACTIVE 



EWRITEERROR 



EWRITSSRROR 



EWRITEZRROR 



Call Noces: 



1. If you only wrice pan of che Iisc, you can specify the order by index number. If you 
wnce ic all, (sizejisc is che same size as che open list) ic writes in ascending order 
regardless of index numbers. 

2. If one of che scacus values is zero, chac variable has noc been read (or perhaps 

scanned) yec, or chac there is a problem such as bad data type or variable noc 

round. Check for an error return. In any case, uval does noc concain a legitimate 
value. * 
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3. If you wish co write all variables in chc open list, macch size_list co che size of the 
open Use Do noc set che individual indices. The Object Manager wrices che lisc in 
ascending order of index number. 

4. There is a macro, v_varlist(s), chac statically or dynamically allocates chc value 
structure for you. This macro is defined in che om_user.h include file: 

#cefine v_varlist (s) valloc (sizecf (scrucc value) *s) 
The following is an example of how this macro could be used: 
size_list = 10; 
value_list * v_varlist (10) ; 
if (value_list == (struct value *) NULL) 
{ 

> - 
The first line sets the sizejist calling argument. The second line dynamically allo- 
cates a. 10-element array of "value" structures. If you use this macro, be sure to free 
chc memory when the structure is no longer needed. It is also advisable to check 
that the macro did not return a NULL pointer indicating insufficient available 
memory 

5. Masks are not specified for data types OM_S_PKBOL and OM_L_PKBOL, 
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3./ omwrstat- Write Values and/or Status to Opened 
List 

omwmatwrhcs variable daca and/or status co a list opened wich che ornopen call. This call 
allows writes co any or all entries in a list, omvmtath asynchronous if the variable is noc in the 
local station; it initiates the omwrite message and returns control to your process/task. 
gerualam verify any omwrite regardless of the delta. If che write changes the value by the vari- 
able list delta or changes the status, it can be verified by either of two ways: 

L If the variable NOTIFY option is set, use dqchange or dqlist to verify che write. 
2. An omread issued after che Use scan race period can also be used. 
Format: 

inc omwrstat (<omopen.ic>,<si2e.list> / <var_list>5 ; 
int cmcpen_id, siza_list; 

struct valstat *var_list; 

Where: . 

omopen_ia The open_id returned by the ornopen call. 

si2s — list The number of valscac structures in the varjist. 

* var - lis fc A pointer to the struct valstat array. 

A valstat structure contains the following elements:. 

struct valstat { 



int 


index; 






unsigned int 


status; 






unsigned int 


setstat? 






unsigned int 


setiaask; 






unsigned int 


setonly; 






union 


{ 








char 




letter; 




int 




word; 




long 




longint; 




unsigned 


int 


uword; 




unsigned 


long 


ulong; 




float 




f ?c int; 



} uval ; 



Where: 

index 

status 



The number (0 base) of che variable list entry co be wricten. 

The data type of che variable (low order byte filled in by che caller). 
An error return code (next co low order byte.' . 
1 = Variable noc on scan. 
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2 = The user specified data type does noc match che actual daca cype. 

3 = The index is <0 or greater than the size of the list. 

4 = Setmask contains invalid bits.. 

The bit settings of those bits specified to be written in setmask. 

The status bits to be written or NULL. Valid bits are OM_STAT_BAD 
and OMJTKTJOOS as defined in OM JJDEEH. 

If TRUE, write status only for this valstat entry. Ignore uval 

The value to be written. 

No error. 

System resource availability problem. 

The specified list has no been opened successfully. No writes are per- 
formed. 

The specified list has not been opened successfully because a variable in the 
list has been secured by another open list. No writes are performed. 

The list is opened for read-only access. No writes are performed. 

The list was not opened successfully because one or more server stations 
have used up all its allotted IPC channels. No writes are performed. 

The list was not opened successfully due to one of the following: 

1. A remote scanner daa base is full. 

2. Optimized network address table is foil. 

3. IPC send problems. 
No writes are performed. 

Not all remote variables in the list have been found/opened. No writes are 
performed. 

The size of the write variable array is < ■ 0 or greater than the size of the 
open Use No writes are performed. 

ENOT active An IPC error was encountered when sending an omwrite message to a 
remote server station. Variables may have been written to other stations. 

For each variable in the write list, validity checks are performed. If an error is encountered, an 
error code is set in the high byte of the callers write list variable status. All variables are 
checked, even if an error condition is encountered in the loop. An EWATT return has priority 
over EWRTTERROIL If any error is encountered no writes are performed. 

EWAIT A variable is not on scan. The (write list variable status) error code is set to 

1. 

EWRITEZRROR The write list variable cype (set in status) does not match the open list vari- 
able type. The error code is set to 2. 



seestat 
setzaask 

setonly 
uval 

Return Codes: 
OM_SUCCZSS 
ENOS?ACS 
ENOT OPENED 

ES2CURE 

EWRITE 
0M_SC3SY 

ECONNBAD 



ESTATION 



EOMWSIZE 
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EWRITESRROR The wricc Use variable index is greater chan che size of the lisc (header 
cur_size_openJist). The error code is sec co 3. 

EWRITESRROR The setmask contains bits set other chan OM_STAT_OOS or 
OM_STAT_OOS. The error code is set to 4. 

Call Notes: 

1. If you only write parr of the list, you can specify the order by index number If you 
write it all, (sizejist is the same size as the open list) it writes in ascending order 
regardless of index numbers, 

2. If one of the status values is zero, that variable has not been read (or perhaps 
scanned) yet, or chat there is a problem su^h as bad data type or variable not 
found. Check for an error return. In any case, uval docs not contain a legitimate 
value. 

3. If you wish to write all variables in the open list, match size_list to the size of the 
open list. Do not set che individual indices. The Object Manager writes che lisc in 
ascending order of index number. 

4. There is a macro, v_varlist($), chac scacically or dynamically allocates the value — 
scrucnire for you. This macro is defined in the om_user.h include file: 

" See fine v_varlist (s) valioc (sizeof (struct value) *s) 
The following is an example of how this macro could be used: 
size_list = 10; 
value_list * v_varlisc (10) ; 
if (value_list == (s cruet value *) NULL) 
{ 

} 

The fine line sees che sizejist calling argumenc. The second line dynamically alio- 
caces a 10-elemenc array of "value" structures. If you use ehis macro, be sure co free 
che memory when the structure is no longer needed. Ic is also advisable co check 
chac che macro did noc recurn a NULL poincer indicating insufficient available 
memory. 

5. Masks are noc specified for data types OM_S_PKBOL and OM_L_PKBOL. 
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4. C Calls to Locate and Catalog 
Objects 

Locating an object means getting its address. Cataloging means instilling or removing objects 
from the object directory or the import list. 

The object directory contains all the shared objects created by the tasks in the local station. 

The import list contains the names of all data objects that tasks in the local station want to 
import from remote stations. Listed with each name is an index value into the address table, 
which contains the address of the named object. 

The OM C calls to locate and catalog objects are listed in this Section in alphabetical order 
and summarized in Table 4- 1 . 



Table 4*1. C Calls to Locate and Catalog Objects 



Paragraph 
No. 


Call 


Function 


4.1 


globa_6nd 


Find and objects address 


4.2 


import 


Add object to import list 


4.3 


obj_crea.ee 


Add a new object to the directory 


4.4 


obj_delece 


Delete from object directory 


4.5 


°bj_m ul ti_create 


Add multiple objects co the directory 


4.6 


unimport 


Remove object from import list 
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4.1 globaljind - Find an Object's Address 

The giojaijhtd call finds an object and returns its address. This call is synchronous- the «ll 
suspends unril che opcrarion is compiece. °nous, the call 

Format: 

inc sIobal_ fi:id(<cbj _ ri ^^ 



char 
inc 

PSAP_ADDR 

Where: 
*obj_name 

*?sap_ptr 
Return Codes: 

OM_SUCCZSS 
E3ADTYPE 
ENOTFOUND 
E3ADNAME 
ENOSPACE 
EIPCRST 
' CaUNoce: 



*obj_najae; 

obj_type; 

*?sa?_ptr; 



A pointer to the name of the object to be located. 

The objects type, which can be one of the following VARIABLE AI TAS 
PROCESS, or DEVICE. 

A pointer to the location where global_fiind returns the objects station 
address. 



The call successfully returned a valid address. 
The specified object type is invalid. 
The named object could not be found. 
The object name is invalid. 
There is a memory allocation error. 
An unspecified IPC error. 



The address buffer is modified if the call feils. Be sure to check for an error return 
before using the address. 
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4.2 import - Add Object to Import List 



The tmportcdl adds a remote object to the local stations import list. The hnoort call is syn- 
chronous; your task suspends until the call is complete. 
Format: 

int import (<naaie>, <obj_type>] 



char 
int 

Where: 
*name 

Return Codes: 

0M_SUCCSS5 

23ADTYPE 

23ADNAME 

ENOTFOUND 

ENOSPACZ 

ELOCAL 

EIMPFULL 

EIPCRZT 

Call Note: 



*name; 



A pointer to the name of the object to be imported. 

The objects type, which can be one of the following: VARIABLE, ALIAS 
PROCESS, or DEVICE. 

The object is now on the import list. 
The specified object type is invalid. 
The specified object name is invalid. 
The object name cannot be found. 
There is a memory allocation error. 
The object you are trying to import is local. 
The import list is too full to add your object. 
An unspecified IPC error: 



If you move an object of cype PROCESS or DEVICE, the import table is hot 
updated. You must unimport, then import these object types to make sure you have 
the most current address. 
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4.3 obj_create - Add a New Object to the Directory 

The obj^crearecall adds a shared object co die object directory and automadcally makes ic glo- 
bal. This call is synchronous; your task suspends unci! che call completes. ° 
Format: 

int ob j_create (<r*ame>, <cbj_type>, <var_type>, <s-r_!ar.>} 



c.-iar 
int 

Where: 
*naae 
ob j_type 

var_type 



str_len 
Return Codes: 

OJ*_SvJCCES5 

ESTRLZN 

E3ADTYPE 

E3ADNAME 

EDUPLICATZ 

E03JPND 

EIPCRET 

ENOSPACS 



obj_type,. var_ty?e, str_len; 



A pointer- co che objects name. 

The objects type, which can be one of che following: VARIABLE. ALIAS 
PROCESS, or DEVICE. - 

The data type of che objects value, which can be one of che following 
CHARACTER, INTEGER, FLOAT, STRING, OMJLNG INT, * 
OMJJOOL, OM_S_PKBOL, or OMJLJPKBOL. 
An alias jnust be of variable type STRING. var_typ e should be zero for 
object types PROCESS and DEVICE. . 

The string length for VARIABLE and ALIAS objects. 

The new object is now in che object directory. * " 

The string length is invalid. 

Either the object or data type is invalid* 

The specified object name is invalid. 

That object name already exists in the directory. 

That object is being created by another task. 

An unspecified IPC error. 

No memory available, try again later. 
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4-4 obj_delete - Delete From Object Directory 

. cn ln uneaiacely rcmrns concrol co /our cask. 

Formac 

inc objJ iIiCf(<n ^ >(<obLcypi>) 



char 
infc 



•name; 
obj^type; 



Where: 
*naae . 



A pointer co che name of che object co be deleced. 

m^!^DE^ " ^ ° f f ° ll0Win§: VAWABLE > ALIAS, 
Return. Codes: 
OM_SUCCZSS 
E3ADNAMH 
E3ADTYPE 
ENOTFOUND 
Call Note: 

If a deleced object was connected, it becomes disconnected and any task trvinc m 

• sn^r^ 



The request has been initiated successfully. 
The specified objea name is invalid. 
The specified object type is invalid. 
The specified object is not in the directory. 
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4.5 obj_multi_create - Add Multiple Objects to the 
Directory 

The obj_7nulti_create call adds multiple shared objects co the object directory from a single 
Object Manager call. All objects are verified for uniqueness, and all objects share a common 
network timeout period. This call is synchronous; your task suspends until chc call completes. 

Format: 

int obj_multi_create (<obj_ptr>, <num_cbjects>) 
struct abject_plus *object_ptr 
int num_objs 

Where: 

obj_ptr : The objects pointer to the array of cb jecc_plus object definitions struc- 
tures (from cra_ucat . h) 

object_ptr->name[ ]: 
* NAMEJ-EN+l alphanumeric characters of the objects name 

object_ptr->object_type: 

Object type (VARIABLE, ALIAS, PROCESS, DEVICE, etc) 
ob j ec t_p tr->ty?e: 

The data type of the objects value, which can be one of the following: 
CHARACTER, INTEGER, FLOAT, STRING, OM_LNG_INT, 
OM _BOOL, OM_SJ>KBOL, or OM_L_PKBOL 

object_ptr->str_len: 

If the type is STRING, the string length. 

num_ob j ects: The number of objects to be created (< or = MAX_REG_SIZE from 
om_ucef.h) 

Outputs: 

object _ptr->status : 

ob ject_plus structure member updated for each object of the array 

Return Codes: 

om_success The new object is now in the object directory 

The following returns might be considered warnings, and as such, some of the objects in the 
array could have been created. In the event more than one of them has occurred, they are 
returned in the order listed. 
ENOSPACS The object directory is full 

EOBJPND The object in the array is a duplicate of an object pending creation 

. EDUPLICATE An object in the array is a duplicate - local or remote 
The following errors are considered syntactical errors and prevent all objects from being cre- 
ated. 

E3ADTYPS Either the type is out of range or invalid for the object type 
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E3ADMAME The specified object name has a non-alphanumeric character, or was coo 

long 

ESTRLZN A STRING variables str_len was improper 

E?OHT Object Manager internal error 
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4.6 unimport- Remove Object From Import List 

t T imj ' 0rt ^ 1 rcmovcs » object from chc local stations import Bsc The unhnpon^X is 
asynchronous; « initiates the request then immediately returns control to your cask. 
Format: 



iac unimport{<aame> # <obj.ty?e» 
'name; 



char 
int 



Where: 
*aaae 

Return Codes: 
OM_SUCCESS 
HBADTYPE 
H3A0NAME 



A pointer to the name of the object to be removed. 

The objects type, which can be one of the following: VARIABLE ALIAS 
PROCESS, or DEVICE. . ' 

The object was successfully removed. 
The specified object type is invalid. 
The specified object name is invalid. 
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5. FORTRAN Functions to Get/Set 
Object Values 



These functions read and write object values. The/ are connectionless functions, best suited 
for situations in which you wane a single transfer of data. As explained in che document on 
Inter-Process Communications, connectionless functions are functions chat transfer data 
between tasks without having first established an IPC connection (channel). The Object 
Manager registers your task with IPC for connectionless service. Be sure to declare the data 
cypc of the function name if you are interested in checking possible error returns. 

FORTRAN ObjecFManager programs for the AP10/AP20 I/A Series stations use a 16-bit, 
integcr*2 for object values. The format for each function described below uses the inter*2 for 
object values. . 

FORTRAN Object Manager programs for the 50 Series Application programs must adhere to 
che following conventions: 

♦ All integers must be either INTEGER or INTEGERS (not INTEGER*!). 

♦ Access to OM Control and I/O BOOLEAN Variables must be made through the 
50 Series FORTRAN compiler type: BYTE. 

To compile FORTRAN programs on 50 Series processors, use the command string: 

f?7 tst.f -If ox -10M77 
The FORTRAN functions to get/set object values are listed in this Section in alphabetical 
order and summarized in Table 5-1 . 



Table 5-1. FORTBAN Functions, to Get/Set Object Values , 



Paragraph 






No. 


Call 


Function 


5.1 


GETVAL 


Gee the value of an object 


5.2 


SETCON 


Se: che value of an objec: | 


5.3 


SETVAL 


Set the value of an object | 
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5.1 GETVAL - Get the Value of an Object 

Use GETVAL to read the value of a specified object. This function works for shared variables, 
process variables, and aliases. GETVAL is synchronous; ic suspends your cask until GETVAL 
completes. 

Format: 

X = GETVAL (<r.ame>,<objcyp-, <is?orz>, <value>, <scacus>, catler.) 



integer*2 
character *3 3 
integer*2 
character *x 
(or real 
(or integer 
(or integer*2 



GETVAL 

nana 

import:, 

value 

value) 

value) 

value) 



status, datlen, objeyp 



mere: 
name 
objtyp 
import 

jralue 
status 



datlen 
Return Codes: 
om.success 
enotfound 

E3ADTYPE 

ENOSPACE 

E3ADNAME 

E3ADLEN 

TO_BIG 

EM0VALUE 



The name of the object. 

The named objects type; VARIABLE or ALIAS. 

1 = place the objects name on the import list, 
0 = do not place it on the import Use 

The objects value. Specify its size in bytes using daden. 

The objects status (data type). An ALIAS object type can only have charac- 
cer data type. 

The regular shared VARIABLE object type can have a data type of CHAR- 
ACTER, INTEGER, INTEGERS, or REAL. 

The Object Manager does not restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, INTEGER*!, and - 
REAL. 

Integers are signed, unless the block parameter definition specifies other- 
wise. Reals adhere co the IEEE standard. 

The length (bytes) allocated for "value." 
No errors. 

Object not found (locally or globally). 
Illegal object type. 

No memory available; no value returned. 
Invalid object name. 
Shared variable is coo big for daclen. 
Process variable is coo big for daden. 
Specified object cype has no value. 
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EBAdvrsc Value is corrupt, invalid daca cypc. 

EIMPFULL The import list is full; value returned, but not added co list. 

eipcret You have an unspecified IPC error. 

Call Notes: 

1. Placing a local object (one found in the same station) on the imoort list is unneces- 
sary, so for local objects GETVAL ignores that option. However, the value is still 
returned. 

2. Return code ENOTFOUND might mean that the object does not exist locally or 
globally. If the object exists in a remo te starion, then that station might be down 
Iht CaSC ' ° bjCCC M2Lnagcr rcmovcs chc ob i ec « name from the import 

3. If you do not make daden large enough, value will be too small to hold the 
returned value. In such a case GETVAL returns as much data in value as will fic. 

4. If datlen is too large, value will contain unused bytes. GETVAL does not close-uo 
this unused memory space. 
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5.2 SETCON - Set the Value of an Object 

SEl CONscxs the value of a specified object and waits for confirmation chat ic was sec This 
call works for shared variables, process variables, and aliases. SETCOiVis synchronous; it ini- 
tiates the request then suspends processing until the operation is complete, 
Formac 

X - SETCON (<narae>, <objtyp>, < import >, <value>, <scatus>, <d=ilsr.>) 



integer*2 
character 
integer* 2 
character-x 
(or real 
(or integer 
(or iEE!ger # 2 



SETCON 
n&ae 

import, datlen, status, cbjty? 

value 

value) 

value) 

value) 



Where: 




name 


The name of the object. 


objtyp 


The named objects type; VARIABLE or ALIAS. 


iaport 


1 = Place the objects name on the import list. 
0 = Do not place it on the import list. 


value 


The value to be set. Specify its size in bytes using daden if it is a string or 
□rocess variable 


status 


The objects data type. The possible data types are listed in FORTRAN 
Functions to Get/Set Object Values on page 79. 


datlen 
Return Codes: 


The length (in bytes) allocated for "value." This is only needed for charac- 
ter data types and all process variables (regardless of data type). 


OM_SUCCESS 


The value has been successfully set. 


N0T_SETTA3LE 


This is not a settable process variable. 


SECURED 


Process variable secured; can t be set. 


EKOTFOUND 


Object not found (locally or globally). 


E3ADTY?£ 


Illegal object type or data cype. 


E5ECCJRE 


Object is secured and cannot be sec. 


ENOSPACE 


No memory available; value noc set. 


E3ADNAME 


Invalid object name. 


SSTRLEN 


The string length is invalid. 


ENOVALUE 


Specified object type has no "value". 


E3ADVREC 


"Value" is corrupc, invalid daca cype. 


EIMPFULL 


The import list is foil; value set. 
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ii?CR£T You have an unspecified IPC error. 

TO_RZAL_CQNV_ERROR 

Process- variable cype-conversion error. 

TO_INTEGZR_COMV_ERROR 

Process- variable type-conversion error. 

TO_STRING_CONV_ERROR 

Pro cess- variable type-conversion error. 

TO_3O0L_C0NV_ERROR 

Process-variable cype-conversion error. 

Call Notes: 

1. Placing a local objecr (one found in che same scacion) on che imporc list is unneces- 
sary, so for local objects SETVAL ignores chac op don. However, che value is sail 

sec 

2. ENOTFOUND might mean chac che objecr does noc exist locally or globally. If 
the object exists in a remote starion, chen that starion might be down. In either 
case, the Object Manager removes the objects name from the import list. 

3- Ifdaden is too small, SETCON truncates the value co fit. 

4. Ifdaden is too large, value will contain unused bytes, SETCON does not close-up 
this unused memory space. 
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| 5.3 SETVAL - Set the Value of an Object 



SETVAL sets the value of che specified object. This function works for shared variables, pro- 
cess variables, and aliases. SETVAL is asynchronous; it initiates the request then immediately 
returns control to /our task. 
Format: 

X = SETVAL (< name >, <ofajty?>, <i:ncarc>, <value>, <scarus>, <daclar*>) 
integer*2 SETVAL 
character nasia 

integer w 2 import, datlen, status, objty? 

characters value 
(or real value} 
(or integer value) 
(or integer*2 value) 



mere; 
name 
ob j typ 
import 

value , 

status 



datlen 

Return Codes: 

om_succzss 

n0t_settable 

SECURE 
ENOT FOUND 
E3ADTYPE 
ESECURE 
ENOSPACE 



The name of the object. 

The named objects, type; either VARIABLE or ALIAS. 

1 s Place the objects name on che import list. 
0 = Do not place it on che import list. 

The value to be sec Specify in size in bytes using datlen, if it is character or 
a process variable. 

The objects data type. 

An ALIAS object type can only have character data cype. 
The regular shared VARIABLE object type can have data, types of CHAR- 
ACTER, INTEGER, INTEGERS, and REAL. 

The. Object Manager docs not restrict process VARIABLE data types, but 
they can be of types CHARACTER, INTEGER, INTEGER*!, and 
REAL. . 

Integers are signed, unless the block parameter definition specifies other- 
wise. Reals adhere to the IEEE standard. 

The length (in bytes) allocated for value. This is needed only for charac- 
ter data types and all process variables (regardless of data type). 

The set request has been initiated successfully. 
This is not a settablc process variable. 
Process variable secured; cane be sec. 
Object not found (locally or globally). 
Illegal object type or data type. 
Object is secured and cannot be set. 
No memory available; value not sec. 
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E3ADMAMS Invalid object name. 

ESTRL2N The string length (daajen) is invalid. 

ENOvaluz Specified object type has no "value". 

E3ADVREC • "Value" is corrupt, invalid data type. 
EIMPFULL The import list is full; value sec. 

SIPCRST You have an Unspecified IPC error. 

TO_RZAL_CONV_ERROR 

Process-variable cype-conversion error. 
TO_INTEGZR_CONV_ERROR 

Process-variable cype-conversion error. 
TO_STHING_CONV_ERROR 

Process-variable cyp e-co nversio n erro r. 
T0_300L_C0NV_ESil0R 

Process-variable type-conversion error. 

Call Noxes: 

1. Placing a local object (one found in the same station) on the import list is unneces- 
sary, so for local objects SETVAL ignores that opdon. However, the value is sail 
sec 

2. ENOTFOUND might mean that the object does not exist locally o r globally. If 
the object exists in a remoce stadon, then that starion might be down.°If so, the 
Object Manager removes the objects name from che import list. 

3. If daden is too small, SETVAL truncates the value co fit. 

4. If daden is too large, the value will contain unused bytes. 
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6. FORTRAN Functions to Access/ 
Update Sets of Variables 

These calls allow your cask co establish a delta value for each of a list of process variables (using 
OMOPEN). The delta value is how much change has to take place in the variables value 
before your cask is no rified (by DQCHNQ . 

The variables in an opened list are maintained locally so that the response on reads is immedi- 
ate and requires no network traffic; These calls arc designed for casks needing ongoing access 
co many process variables. 

A cask can read from or write to variables on a list opened wich OMOPEN until the occur- 
, rence of until issuing an OMCLOS, call, at which dme the Object Manager returns a table of 
• - addresses where it found the variables. Subsequent OMOPENs can use the same table of 
addresses, thus saving processing dme. 

FORTRAN Objecr Manager programs for the AP10/AP20 I/A Series stations use a 16-bit, 
inccgcr*2 for object values. The format for each function described below uses the inter 11 ! for 
object values. 

FORTRAN Object Manager programs for the 50 Series Application programs must adhere to 
the fo Uowing convenrio ns: 

♦ All integers must be either INTEGER or INTEGERS (not INTEGERS). 

♦ Access to OM Control and I/O BOOLEAN Variables must be made through the 
50 Series FORTRAN compiler type : BYTE, 

In addidon, when performing reads/writes of OM BOOLEAN types in lists, a four BYTE 
array must be EQUTVALENCEd to an INTEGER, as shown in the following example: 

BYTE BYTEVAL (4) 

INTEGER INTVAL 
EQUIVALENCE (BYTEVAL, INTVAL) 

OMREAD (OPENID, NUMVAR. INDEX, STATUS , INTVAL) 

then to access the byte, reference element 0: 

VALUE = BYTEVAL (0) 

The FORTRAN functions to access/updace sets of variables are listed in this Section in alpha- 
betical order and summarized in Table 6-1. 
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Table 6-1. FORTRAN Functions to Access/Update Sets of Variables 



Paragraph 
No. 


CaU 


Function 


6.1 


DQCHNG 


Check for object value changes 


6.2 


OMCLOS 


Close die soecified variable Use 


6.3 


OMOPEN 


Open a sec of variables 


6.4 


OMREAD 


Read values from opened list 


6.5 


OMWRI 


Wrice values co opened Use 
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6.1 DQCHNG - Check for Object Value Changes 

The DQCHNG function checks co see if any values in any OMOPENed variable Uses have 
changed Ic checks all che lists for die cask named and recurns changes in che first variable lisc 
ic finds. In order co register as a change, che new value has co be greace: chan or equal co che 
delca value (in OMOPEN) for chac value. To be notified, set che notify option in OMOPEN. 
Format: 



r > 
■/■ 
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DQCHNG (< 

integer*2 

integer*2 

integer*2 

integer*2 

irxcager*2 

integer*2 

integer 

integer* 2 



Where: 

flag 

openid 

qsize 
qindex(y) 

qs tatty) 
value (y) 



:lag>, <openid>, <qsize>, <qindex>, <qstar>, <value>, <rqsize>) 
DQCHNG 
flag 
openid 
qsize 
qindex(y) 
qstat(y) 
value (y) 
rqsiza 



0 = don t suspend, 1 = suspend. 

A value returned co che caller chac identifies a previous omopen call whose 
list has changed. 

Number of elements in value array. 

Where y - qsize, the index value into the variable list corresponding to 
the variable chat changed. 

An array of status of changed variables. 

An array of values for each entry in the lisc. value (y) must be declared 
in four bytes or floating poinc, even if the value is character data cype. 

Example of a mixed variable cype list: 

rqsizeThe number of eiemencs rccurned. 



Return Codes: 

OM_SUCC£SS 

E5ECURZ 

EMOTOPENED 



characters 

integer 

real 

equivalence 



charva (y) 
ival (y) 
readva (y) 
(charva, ival, 



readva) 



Changed variables have been successfully returned. 

One or more variables in che lis: is secured, so dqchange will noc work on 
chis lisc. 

The specified cask has no variables sec for notification access, or no opened 
lists. 



ECOMNBAD 
EQNOTZKFTY 
EQ EMPTY 



Section 6. FORTRAN Ftf 



jAccass/UpdateSets of 



Call Noces: 



1 he OMOPEN could noc establish an IPC connection. You should close 
the Use 

The value array is cob small co hold all che changes char the Object Man- 
ager has in its queue. 

You did noc specify che suspend opcion and chere were no changes in che 
Object Managers queue. 



1. You can specify any cask name (process id) chac has open lists. If more chan one 
open list has changes in it, DQCKNG returns che changes in the first list, then 
remove chat list from its queue. Use anocher DQCHNG call to get the changes in 
the next list. " ° 

2. Each variable lisc is identified by che open id returned when che lisc was opened. 
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6.2 OMCLOS - Close the Specified Variable List 

The OMCLOS call doses a list of local or remoce variables by releasing the connection estab- 
lished with the OMOPENadL It also supplies all of the header information, variable list, and 
address caolc to speed up future OMOPENadls to the same list. 

OMCLOS is asynchronous; it initiates the request then immediacely rerums concrol co your 
task. 7 

Format: 

X = OMCLOS (< numvar >, <c?e.iid>) 
inteser*2 OMCLOS 
intager*2 numvar 
incager»2 openid 

Where: 

numvar The number the number of variable names in the specified openid. 

openid The id from the previous OMOPEN. 
Return Codes: 

OM_saccHss The request has been initiated. 

ENOTOPEMED There is no open list corresponding to c?e.i_id. 

EI5CRHT You have an unspecified IPC error. 
Call Note: 

It is imperative that the lists be closed before any exit from the program. 
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6.3 OMOPEN - Open a Set of Variables 

The OMOPEN 'call opens a list of up co 255 local or remote variables. You must use this call 
before using any of the other daca access calls. This call is asynchronous; ic initiates the request 
then immediately returns control co your cask. 
Format: 

X = OMOPEN (<:iusrvar>,<nanie>, <delta>, <notify>, <rvacc>, <c?enid>, <scr.rsc>) 

integer* 2 OMOPEN 
character *3 3 name (y ) 



integers 


nunrvar , 




delta (y) , 




nctify(y) , 




rwacc , 




openid 


integer* 2 


senrat 


Where: 




nane 


An array of x names in the list. 


nunvar 


The number of variable names. 


delta 


An array of delta values; one for each variable name. 


notify 


An array of change notifications; one for each variable name. 


rwacc 


Read/write access for the list. 


opanid 


An id returned co the- user. 


s carat 


The rate at which the station that gen the data sends it co the station that 




opened the Use This can be a value from 1 to 120 half-second intervals. An 




invalid scan rate defaults co one (1/2 second interval). 


The FORTRAN call only uses the unoptimized version, which takes up less memory You 


provide a list of variables, the Object Manager uses its own address cable. 


Return Codes: 




OM_SUCCESS 


The list has been opened. 


ENOTFOUND 


One or more variables can't be found; the rest are being scanned. 


E5ECURE 


Attempt to open a secured variable; the list is open, but no write access to 




any variables. 


ENOSPACE 


There is not enough room in memory, cry again later. 


EOPEMED 


The list has already been opened. 


EC0MN3A0 


List open but not connected, no wrice access. 


ENCAD DTE L 


Previous OMOPEN 'for chis list had an address cable; che list is open, buc 




not scanned. 


ENOSE^^D 


List open, but remotes, are not connected or scanned, local variables are 




being scanned. 
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esjucopns The OMOPENid cable is foil; list noc opened. 

ESCAWFUL List open, buc che local scanner database too small; variables that fit in the 

database are being scanned. 
£I?casT You have an unspecified IPC error. 

Call Notes: 

1. Ic is faster if the variables you wane to access are already listed in the import list 
(Refer to the IMPORT call.) 

2. All the specified variables are scanned every half-second. You can pick up chose 
wtch changes greater than or equal to the delta value wich a DQCHNG or 
OMRjEAD. 

3. Unlike che C call, which has both optimized and unoptimized versions, this call is 
unoprimized. This saves space by using che Object Managers address able. This 
cable is used by many functions wichin che local scacio n. Your variable address 
found and added each rime you open che list 

Use che openid when you issue che OMCLOS call. 

5. Ic is imperative chac che lists be closed before any exit from che program. 



;esare 



6. 
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6 A OMREAD - Read Values From Opened list 

The OMREAD call reads variables from ehe lisc opened with che OMOPENcall This call 
allows you co read all or any part of che lisc. You can read parts of che lisc in any order. This 
call is asynchronous; it returns co pur cask as soon as ic has been initiaced. You must check 
the status in the value structure co see if ic completed. 
Format: 

X = OMREAD (<op«nid> # <aumvar>.<index>,<status>,<r«acva>) 
integers OMREAD 

integers openid, numvar, index (y) , scatus(y) 

raacva 



integer 

Where: 
openid 
nuxnvar 
index (y) 

status (y) 
readva(y) 



The openid returned by the OMOPEN call. 
The number of entries co be read. 

Where x = numvar; the entry you wish to read from che list. If numvar is 
noc specified che defaulc is to read che entire lisc 

An array of read statuses for each entry in the list. 

An array of values for each entry in the list. readva(y) must be declared in 
four bytes or floating point, even if the value is character daca type. 

Example of a mixed variable type-list: 

character* 4 charva (y) 
ival (y) 
raadva (y) 

{charva, ival, raacva) 



integer 
real 

ecruivalance 



Return Codes: 

OM_SUCCESS 

ESECURS 

ENOTOPENED 

EREAD 

ECONNBAD 

ESCANFvJL 

Call Noces: 



The list has been read. 

Attempc co open a secured variable. 

List is noc opened (or bad om_descripcor). 

The OMOPEN 'call was sec for wrice only. 

Unable co connect to rcmoce station. 

List open, local scanner dacabase coo small; variables chac fic in che dacabase 
are bein? scanned. 



1. For mulciple errors, che return code shows only one. E READ ERROR is super- 
ceded by ESCANFUL which is superceded by ECONNBAD. 

2. To only read pare of che lisc, you can specify che order. If you read che whole lisc, ic 
reads in ascending order. 
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3. If one of die stacus values is zero, chac variable has noc been read (or perhaps 
scanned) yet, or there is a problem such as bad data cype or variable not found. 
Check for an error return. In any case, uval does noc concain a legirimace value. 
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6.5 OMWRIT - Write Values to Opened List 

The OmVRlTadl writes variables to the array opened with the OMOPEiVail This call 
allows you co write all or any part of the array. You can write parts of the array in any orde^ 

, , * aSyndlronous ' " rccuras » your ^ * *>on as it has been initiated. You must 
check status to see if it completed. 

Format: 



X 



OMWRIT 

integer 
integer 
integer 
integer 
integer 
integer 



Where: 
openid 
nusivar 
index (y) 

status (y) 
writva (y) 



Return Codes: 

OMJSUCCESS 

ESECURE 

ENOTOPENED 

EWRITEZRROR 

EWRITE 

ECONNBAD 

EC MSI 2 E 

EWAIT 

ESTATION 

ENOSPACE 



(<oper.ic> / <^umvar> / <incex>, <status>, <writva>) 
'2 OMWRIT 
*2 openid 
*2 nuiavar 
*2 index (y) 

# 2 status (y) 

writva(y) 



The openid returned by the OMOPENadL 
The number of entries to be written. 

Where x = numvar; the entry you wish to write to the list. If numvar is not 
specified the default is to write the entire list in sequential order. 
An array of write statuses for each entry in the list. 

An array of values for each entry in the list, writva (y) must be declared in 
four bytes or floating point, even if the value is character data type. 
Example of a mixed variable type list: 
character^ charva (y) 
integer ival (y) 
real writva (y) 

equivalence (charva, ival, writva) 

The list has been written. 

Attempt to write a secured variable. 

List is not opened (or bad om_descriptor). 

One or more variables inaccessible (check statuses). 

The openid indicates a read-only access. 

Unable to connect to remote station. 

Value list is < 1 or larger than opened list. 

Remote scanner(s) havent updated the list objects. 

All remote stations havent responded. 

Cannot allocate message space for remote write. 
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You have an .unsoedfied IPC error. 
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EISCRET 
Call Notes: 

1. If you only write part of che list, you can specify die order by index number. If you 
write it all, it writes in ascending order regardless of index numbers. 

2. If one of the status values is zero, that variable has no t been read (or perhaps 
scanned) yet, or that there is a problem such as bad data type or variable not 
found. Check for an error return. In any case, uval does not contain a legitimate 
value. 



80,9380 - 0Ct0ber 3 1995 Section 6. FORTRAN fiTv . «o Acce^Updote Sets of 



," J )' ,- EV324849404US 

O « > > 

7. FORTRAN Functions to Locate 
and Catalog Objects 



Locating an object means getting its address. Cataloging means installing or removing objects 
from the object directory or the import list 

The object directory contains all the shared objects created by the tasb in the local station. 

The import list contains the names of all data objects that tasks in the local station want to 
import from remote stations. Listed with each name is an index value into the. address table, 
w hich c ontains the address of the named object. 

FORTRAN Object Manager programs for the AP10/AP20 I/A Series stations use a 16-bit, 
integer*2 for object values. The format for each function described below uses the inter*2 for 
object values. 

FORTRAN Object Manager programs for the 50 Series Application programs must adhere to 
the following conventions: 

♦ All integers must be either INTEGER or INTEGERS (not INTEGER"!). 

♦ Access to OM Control and I/O BOOLEAN Variables must be made through the 
50 Scries FORTRAN compiler type : BYTE. 

The FORTRAN functions to locate and catalog objects ar^ listed in this Section in alphabeti- 
cal order and summarized in Table 7-1. 



Table 7-L FORTRAN Functions to Locate and Catalog Objects 



Paragraph 
No. 


Call 


Function 


7.1 


IMPORT 


Add object co imporc list 


7.2 


OCREAT 


Add a new object to the directory 


7.3 


ODELET 


Delete from object directory 


7.4 


UNIMPO 


Remove object from import list 
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7.1 IMPORT - Add Object to Import List 

The IMPORT call adds a remote object to the local stations import list. IMPORT]* synchro- 
nous; your cask suspends until the function is complete. 
Format: 



int IMPORT (<name>,<abjtyp>) 

character^ 3 nane 

import, objtyp 



intager»2 



Where: 




*naxne 


A pointer to the name of the object to be imported. 




The objects type, which can be one of the following: VARIABLE, ALIAS 




PROCESS, or DEVICE. 


Return Codes: 




OM_SUCCSSS 


The object is now on the import list. 


EBADTYPE 


The specified object type is invalid. 


E3ADNAME 


The specified object name is invalid. 


ENGTFOUND 


The object name cannot be found. 


ENOSPACE 


There is a memory allocation error. 


ELCCAL 


The object you are trying to import is local. 


EIMPFULL 


The import list is too full to add your object. 


EIPCRZT 


An unspecified IPC error. 



(VP 
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7.2 OCR EAT - Add a New Object to the Directory 

The OCREATfanc&oti adds a shared object co che object director/ and aucomarically makes 
ic global. This function is synchronous; /our cask suspends uncil the function compleces. 
Format: 

X = 0CREAT (<narae>, <obj typ>, <varcyp>, <datlen>) 
integer* 2 OCREAT 
mtegar'2 objeyp, vartyp, catlen 

character *3 3 name 



Where: 
name 
obj typ 

vartyp 



datlen 

Return Codes: 

OM_SUCCESS 

ESTRLEN 

E3ADTYPE 

E3 AD NAME 

EDCJPLICATE 

EOBJPND 

EI PC RET 



The objects name. 

The obi ect's type, which can be one of che following: VARIABLE ALIAS 
PROCESS, or DEVICE. 

The data type of che objects value,- which can be one of che following 
CHARACTER, INTEGER, FLOAT, or CHARACTER. An alias must be 
of variable type CHARACTER, vartyp should be null for object types 
PROCESS and DEVICE. 

The character string length, for VARIABLE and ALIAS objects. 

The new object is now in the object directory. 

The string length is invalid. 

Either che object or data cype is invalid. 

The specified object name is invalid. 

That object name already exists in che directory. 

That object is being creaced by anocher cask. 

An unspecified IPC error. 
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| 73 ODELET- Delete From Object Directory 

The ODELET C2l\ removes an object from che object director/. Ic is asynchronous; ic initiates 

chc request then immediately returns control co your task. 

Format: 

X = ODELZ? (<naae>,<objtyp>) 

ODELET 
character '3 3 name 
intagar~2 objtyp 

Where: 

narae The name of the object co be deleted. 

-Sfelpyp The objects type, which can be one of the following: VARIABLE ALIAS 

PROCESS, or DEVICE. w ^ ^ ' 

Return Codes: 

OM_succ£SS The request has been initiated successfully. 
E3ADMAMH The specified object name is invalid. 

E3ADTYPE The specified object cype is invalid. 

HNCTfound The specified object is not in the director/. 

Call Note: 

If a deleted object was connected, it becomes disconnected and any task trying co read 
or wnte it is notified that it is disconnected (in the status part of chc value structure). 
| Since there is no error or warning returned when this happens, it is up to you to make 

sure you do not delete the wrong objects. 
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| 7.4 UNIMPO - Remove Object From Import List 
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The ^YBffo fimcuon removes an object from die local stations imoort list. This function is 
asynciironous; ,c initiates che request then immediately returns control to your task. 
Format: 

X * UNI.MFO (<nan»>.<objeyp>J 
integer'2 UNIMPO 
character- 3 3 name 
intager-2 objeyp 

"Where: 

name -p fte name Q f cfte 0 bj cct co b c removed. 

ob j typ -fhe objects type, which can be one of the following: VARiABiE ALIAS 
PROCESS, or DEVICE. 

. Return Codes: 

OM.succzss The object was successfully removed. 

E3ADTYPE The specified object type is invalid. 

E3ADNAME The specified object name is invalid. 
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Appendix A. OM Calls Sample 
Programs 



A.I OM Program Creates and Initializes Variables 

Sinclude <stdio.h> 
^include <fox/om_user .h> 
^include <fox/otn_ecode.h> 

main() 
{ 



float value = 6.0; 

unsigned iixc status = FLOAT; 

iat static data_len; 

data_len = 4; 

rtn - obj_creat e ( " CM?1_TI 1_FMT * , VARIA3LE , FLOAT ) ; 

rtn = setval ( * CMP1 JTI1_PNT- , VARIABLE , 0 , &value , Sstacus , &cata_ler.) ; 
printf <«rtn = %d\n",rtn); 

rtn = ob j_craate("CMPl_TI2_?NT", VARIABLE, FLOAT) ; 

rtn a setval ( -CMP1_TI2_PNT- , VARIABLE, 0,&value, Sstatus, tdata.len) ; 
printf (-RTN » %d\n',rtn) ; 

rcn ■ 6b j_create("CMPl_TI3_?MT", VARIABLE, FLOAT) ; 

rtn = setval rcMPl_TI3_PNT", VARIABLE, 0 , ftvalue, istarus, &data_len) ; 
Printf ("RTN » %d\n", rtn) ; 

rtn = ob j_create(«.CMPljri4_PNT", VARIABLE, FLOAT) ; 

rtn » setval ("CMP1_TI4_PNT", VARIABLE, 0 , fivalue, isttatus, icata.len) ; 

printf ("RTN « %d\n\rtn); 

rtn = obj_create ("CMP2_FC1_MEAS", VARIABLE, FLOAT) ; 

rtn =setval ( *CMP2_FC1_MEAS H , VARIABLE, 0 , fcvalue, iscarus , 6data_ler.) ; 

printf ("RTN = %d\n",rcn); 

rtn = obj_create ("CMP2_FC2_MZAS*, VARIABLE, FLOAT) ; 

rtn -setval { "CMP2_FC2_MEAS" . VARIABLE. 0 , &value, iscatus , &cata_len) ; 

Print f{ -RTN *%d\n-, rtn) ; 

rtn = ob j_create( "CM? 2 _FC3_MEAS". VARIABLE. FLOAT ) ; 

r=n asetval ( "CMP2_FC3__MEAS" , VARIABLE, 0 , tvalue, istacus , &data_Lar.) ; 

printf ( -RTN = %d\n".rtn) ; 

rtn = obj_create("CMP2_FC4_MZA3",VA3IA3LE. FLOAT) ; 

rtn =setval ( "CMP2_FC4_MEAS" , VARIABLE, 0 , &value, istacus , icata.Ler.) ; . 

printf ( -RTN = %d\n-,rtn! ; 

rtn = ob j_createCCMP3_FZ01_P.INI ".VARIABLE, FLOAT) ; 



rtn=setval ( *CMP3_FZ01_RIN1" , VARIABLE, 0, & value, fcscatus , &cata_ler.) ; 
printf ("RTN = %d\n",rta); 

rtn = oh j _cr ea t e { " Of? 3 _FZ 0 1_RIN2 ■ , VARIABLE , FLOAT ) ; 

rcn=satval ( "CMP3_FZ01_RIN2 - , VARIABLE , 0 , &vaiue, iscatus , &cata_len) ; 

printf ( -RTN * %d\n*,rtri); 

rtn = ob j_craate ( "CM?3_FZ01_RIN3 - , VARIABLE, FLOAT) ; 

rtn^setval ( "CHP3_FZ01_RIN3 " , VARIABLE, 0, & value, ftst&tus, &ca=a_!«_) ; 

printf ( -RTN - %d\n*,rcn} ; 

rtn = ob j_create("C21P3_FZ01_RIN4\ VARIABLE, FLOAT) ; 

rtn=setval ( "CMP3_FZ01_RIN4 - , VARIABLE, 0 , fcvalue, ^status, idata.len) ; 

printf ( "RTN = %d\n",rtn); 

} 

A.2 0M Program Opens Two Lists for Reads-and 
Writes 

^include <stdio.h> _ 
^include <fox/om_user.h> 
^include <f ox/om_ecode.h> 

nainO 
( 

strucc open_var in_var_list [8] , out_yar_list [41 ; 

struct header. node in_oro_desc, out_om_desc 

struct net_adr in_net_acr_tbl [2 ] , cut_net_adr_tbl; 

int in_opan_id, out_open_id; 

int rtn; 

float celta_tamp, delta_fc, dalta_df; 

struct value *in_cata_list, *out_data_list, *cemp; 

int i; 

celta_temp ■ 5.0; 
delta_fc » 1.0; 
delta_df = 0.5; 

in_on_desc.ta^k_status = OM_R_ACCESS ; 
in_om_desc.net_adr_tbi_?tr = in_net_acr_tbl ; 
in_om_desc.size_net_adr.tbi = 2; 
in_om_desc.cpen_list_?tr = in_var_list; 
in_om_desc .size_ocen_lisc = 8; 

out_ora_desc. task_status = CM_W_ACC£SS; 

out_orti desc.net adr zhl ccr= Sou: net adr tbl; 
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cut_cm_desc.size_net.adr.tbl = 1; 
°ut_ora_desc.open_lisc_ptr = cut_var_list; 
out_ora_desc.size_open_lisc = 4; 

strcpy(in_vaf_list [0] .name, *CM?1_TI1_?N? " ) ; 
in_var_list[0] .var_desc = NOTIFY ; 
in_var_list[0] .delta = delta_temp; 

s t rcpy ( in_var_l is t [ 1 J .name, "CM?1_TI2_PNT U ) ; 
in_var_list [1 ] .var _desc = NOTIFY; 
in_var_list(l] .delta = delta_temp; 
strcpy{in_var_list 12] .name, "CMP1_TI3_PNT M ) ; 
in_var_list [2] .var_desc = NOTIFY; 
in_var_listt2] .delta = delta_temp; 

rcpy ( in_var_list f 3 ] .name, •CMP1_TI4_PNT'' ) ; 
in_var_list(3] .var.desc = NOTIFY; 
in_var_lisc(3] .delta - delta_temp; 
strcpy(in_var_list [4] .name, -CMP2_FCl_MEAS rt ) ; 
in_var_l is t [ 4 ] . var_des c = NOTIFY ; 
in_var_listC4] .delta = delta_£c; 
strcpy(in_var_list(5] .name, ■CM?2_FC2_MEAS" ) ; - 
in_var_lisv:[5] .var_desc = NOTIFY; 
in_var_list[5] .delta = delta.fc; 
s t r cpy ( i n_var_l i s t [ 6 ] .name, "CHP2_FC3_MEAS« ) ; 
in_var_list[6] .var_desc = NOTIFY; 
in_var_list[6] .delta = delta_£c; 
strcpy(in_var_list[7] .name, 'CMP2_FC4_MZAS- ) ; 
in_var_list[7] .var_desc = NOTIFY ; 
iti_var_list[7] .delta = delta_fc; 

strcpy(out_var_list[0] .name, •CMP3_FZ01_RIN1* ) 
out_var_list(0] .var.desc * NOTIFY; 
°ut_var_list(0] .delta = delta_df; 
strcpy(out_var_list[lJ .name, •CMP3_FZ01_RIN2 • ) 
out_var_list [1] . varices c = NOTIFY; 
out_var_list [1] .delta = celta.cf; 
strcpy(out_var_list(2] -name, ■CM?3_FZ01_RIN3 " ) 
out_var_list(2) .var.desc = NOTIFY; 
out_var_listt2] .delta = celca_.dc; 
strcpy(out_var_list C3 ] .name, •C>!?3_FZ0i_R:M4 t ' ) 
out_var_list[3] ,var_desc = NOTIFY; 
out_var_listC3] .delta = calta.df; 

rtn = omopen(&in_om_desc,&in_open_id) ; 
printf {-Return = %d\n",r-n); 
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Calls Sample Programs 



"a = omopen(&out_om_desc,&cut_open_id) ; 
printf (-Return = %c\n" , rcn) ; 



if ((in -<^ta_Lisc * (struct value -)v_varlisc (8)) WLL) 

printf ( "Can' t allocate space \n"); 

omclose ( in_open_ic, &in_om_desc, in_var_list, 

in_ne t_adr_t b I ) ; 
omclose (cut _open_id, &out_om_casc, out_var_list, 

&out_nec_adr_tbl } ; 
exit(O); 

} 

sleeg( l) r 

i f ( ( rtn = omread ( in_open_id, 8 , in.data^list ) ) ! = 0M_SUCCES3) 

printf (-Return = %c\n-,rtn"J; 

omclose (in_open_id, &in_om_desc, in_.varj.ist, 

in_net_adr_tbl) ; 
omclose (out_open_id, &out_om_desc, out_yar_list, 

&out_net_acr_tbl) ; 
exit(O) 

} 

for (i = 0; i<8; i++) 
{ 

printf (-Variable %d * %f \nM,in_data.list->uval.fpoint) ; 
in_daca_list+.s-; 

} 

if ( <out_data_list = (struct value *)v_varlist (4)) « NULL) 



{ 



printf (-can' t allocate space \n-); 

omclose { in_open_id, &in_onudesc, in_var_lisc, 

in_net_adr_tbl) ; 
omclose (out_open_id, &out_on\_desc, out_var_list, 

&out_net_adr_tbl) ; 
exit(0) ; 



temp = out_data_list; 

for (i = 0; i < 4; i++) 
( 

temp->index = i; 
temp->status = FLOAT ; 
terap->uval.f point * S.0; 



a: 
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temp*+; 
} 

if((rtn = cmwrite (out_open_id, 4 , out_daca_list ) ) 
1= OM_SUCCZSS) 
{ 

priacf ("Return = %d\n"rcn); 

for(i=0;i<4;i++) 
{ 

printff "status = %u\n rt , out_da;:a_list-> 

status) ; 
out_data_list++; 

} 

oraclose(in_open_id, &in_ora_desc, iri_var_lisc, 

.in_net_adr_tbl) ; 
omclase(out_open_id, &out_ora_desc, aut_yar_list , 

&out_net_adr_tbl) ; — 
exit(O); 

} 

omclose ( in_cpen_id, &in_om_dasc, in_var_list , in_net_adr_tbl ) ; 
omclose (out_open_id, &out_onudesc ,• out_var_list , &ouc_net_acr_tbl ) ; 
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Append u t ..'calls Sample Programs 
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Appendix B. OM Error Codes 



Code 


Message 


Code 


Message 


0 


Call execuced successfully 


-30 


Dqchange queue is empcy 


-1 


Noc found 


-31 


No address table 


-2 


Bad diw rvne 


-32 


Unable to get a queue for notification 


-3 


Variable Is secured 


-03 


Unable to send open requests 




List noc opened 


-3$ 


Address taole run 


< 


trror reading iisc 


2 e 
-OJ 


Not activated with IPC 


-6 


List write only 


-36 


Error creating connection table 


-7 


List read only 


-37 


Error creating disconnect table 


-r3 


Error writing list 


-38 


Error creating open id cable 


-9 


Memory allocation error 


-39 


No space to perform again 


-10 


Variable already exists 


40 


Scanner db full 


-11 


Variable is local 


-41 


Error returned from IPC 


-12 


Name is invalid 


-42 


Remote scanner has not resoonded 


-13 


Warning all data noc returned 


-43 


Remote station has not responded 


-14 


String length is invalid 


-44 


Anocher object of chis name is pending 
creacion 


-15 


juiai. aaicau.y opencu. 


45 


No confirmation 


-16 




-46 


Error creating queue for OM VENIX 
task 


-17 


Bad address cable pointer 


47 


Error creating OM scanner task 


-18 


List has connection problems 


48 Error creating 0 M YEN DC cask 


-19 


Dqchange queue noc empty 


49 


Error creating OM server cask 


-20 


Object type has no value record 


-50 


Received fabort 


-21 


Value record corrupced 


-51 


Invalid list size 


-22 


Error creating import list 


-52 


Error creating reconnect queue 


-23 


Error creating object directory 


-53 


Invalid users address cable size 


-24 


Error creating address table 


-54 


Error creating OM reconnect cask 


-25 


Error creating scanner db 






-26 


Import list full 




-27 


Error creating dqchange queue 
cable 






-28 


Error creating a queue 




-29 


Invalid list size 
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Appendix C. OM Calls 

CI OM C Calls Summary 



dqchange 


int dqchange (<pid>, <susper.d>, <cpan_id>, i 
<size_list>,<value_lisc>, <rec_siza>) j 


dqlist 


inc dqlist (<pid> / <suspend>, <open_id>, <siza_lisc>, 
<value_ list>, <ret_ siza>) 


getval 


int getval (<name>, <ob j_type>, <i:sport>, <value>, j 
<status>,<data_len>) j 


getval.list 


int getvai_list (<narae>, <ob j_type>, <iraport>, 
<value>,<status>,<data_len>,<cper* id>,<ov incex>) 


global_find 


int globai_£ind(<obj_name>,<obj_tYoe>,<psac otr>) I 


import | int import (<name>,<obj_tYoa>) 


ohj_create 


int ob j_create (<name>, <ob j_ty?e>, <var_typa>, 
<str_len>) 


obj_delete 


int obj_delete (<name>,<obj_type>) 


obj_multi_create 


int obj_jmilti_create (<obj_pcr>,<num_objacts>) | 


cmclose 


int omclose(<open_id>,<header>,<var_list>, | 
<addr_tbl>) J 


omopen 


int omopen {<oxn w descriptor> / <cpen_id>] j 


omread 


int onuread(<omopen_id>,<size_list>,<var_list>) j 


omwrite 


int omwrite(<omopen_id>,<size list>,<var list>) j 


omwrstat 


int omwrstat(<omopen_id> / <si2e_list> i <var.list>J 1 


om_getval 


int onusretval (<name>, <ob j_type>, <import>, <value>, j 
<status>,<data_len>,<psap_ptr>) j 


onusetval 


int oni.se tval (<name>, <ob j_type>, <iraport>, <value>~ | 
<status>,<data_len>, <psap_ptr>) j 


onuset_confirm 


int onuset_ confirm (<name>, <obj__type>, <import>, 
<value>, <status>, <data_len>, <?sa?_ptr>) 


set_cnf_list 


int set_cnf_list{<naae> # <obj_type>,<import> / | 
<value>, <status> # <data_lari>, <ocen_id>, <ov_inda;<>) | 


set_confirm 


inc sat_confirro(<name>,<cbj_type>,<i:nport>, j 
<value>, <status>, <data_len>) 


setval 


int setval (<narae> / <obj_type>, <impcrc>, <vaiue>. 
<status>, <data_len>) j 


secval_list 


inc setval - list{<name>,<cbj_cype>,<imporc>, ; 
<value>,<status>, <data_ler.>, <ocer._ic>, <ov_ir.ca;<>) 


s C_oms e c_c a n f i rm 

1 


int sc_omseC_conf irm(<nama>, <obj_type>, <im?arc>, \ 
<value>,<staus>, <daca_len>, <?sa?_ccr>, <sc_daca>, i 
<sc_mask>, <st_only>, <appl_wor!<>) » 
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Appendix C OM Calls 



C.2 OM FORTRAN Calls 



! Sw_cm_setval 

! 

1 
i 


int st_om_setval ( <nane>,.<cb j_typa>, <i*port>, 
<value>, <staus>, <data_Len>, <?sap_pcr>, <st_data>, 
<st_raask>,<st_only>,<a?pl work>) 


! st_setcn5 

i 

< 

! 

i 


int sc_sa£cni(<naxa6> / <obj_cy^e>,<i^r;or"> chinos 
<scacus>, <dataj.er>, <sc_data>, <3-_:aask>, <st_on!y>, 
j <appI_work>) 




iat st_satlisc_ccnfir3(<na^5>,<obj tvca>, <irrm 0r t> 
<value>,<status>, <daca_lan>, <cp5«_id>, <ov_indax>, 
<5t_data>,<st_taask>, <st_oniyi, <a?pl_wcrk>) 


st_set_lisc 


int st_set_list(<name>,<obj_type>,<iaport>, 
<value>, <status>, <data_ler.>, <cpen_ic>, <ov_index>, 
<st_data>, <st_raask> # <st_only>, <appl_ work> 


st_setval 


int st_setval {<name>, <ob j_type>, <iaport>, <value>, 
<status>, <data_len>, <st^_data>, <sc_mask>, <s t_oniy>, 
-eapp l_work>) 


unimport 


int unimport (<name>,<obj tvce>) 



DQCENG 


X = DQCHNG (<fIag>,<openid>,<qsi2a>,<qindex>, 
<qstat>, <value>, <rqsize>) 


GETVAL 


X - GETVAL (<naine> , <ob j ty?> , <i^port:> , <value> , 
<status>, datlen] 


IMPORT 


int IMPORT (<name>, <ob j typ> j 


OCREAT 


X « OCREAT ( <name> , <ob j typ> , <var cyp> , <da t 1 en> ) 


ODELET 


X = ODELET (<name>,<gbjty?>) 


OMCLOS 


X = OMCLOS (<numvar> / <openid>) 


OMOPEN 


X * OMOPEN {<numvar> # <naroe> # <delta>,<aotify> # 
<rwacc>, <openid>, <scnrat>) 


OMREAD 


X = OMREAD (<openid>,<nuinvar>,<index>,<status>, 
<readva>) 


OMWRIT 


X = QMWRIT (<openid> t <nuRsvar>,<ihdex>,<stat\is> # 
<writva>) 


SETCON 


X = SETCON (<name> # <objtyp>,<iniport>,<value>, 
<status>,<datlen>} 


SETVAL 


X = SETVAL ( <name> , <ob j typ> , <inrpcrt > , <value> , 
<status>,<datlen>) 


UNIMPO 


X • UNIMPO (<narae>,<objtyp>) 



c 

Index 



c 

Change Queues 48 
D 

datatypes 1 
dqchange 46 
DQCHNG 89 
dqlist51 



C 

GETVAL 80 
gecvaJ 10 
getvaljist 12 
globaljmd 2, 72 

V IMPORT 100 <'^' 
^ import 73 : r 

import list 2, 71 

import table 7 



O 

obj_create74 

obj_delete 75 

obj_multi_create 76 

object directory 7 

Object Manager Address Table 7 

OCREAT101 

ODELET102 

om — getval 14 

om_hcadcr_nodc structure 3 
om_set_confirm 16 
om_serval 18 
OMCLOS 91 
omclose 54, 57 
OMOPEN 3. 92 
omopen 55, 56 . 
Omopen Connections 60 
Omopen Server Broadcast 60 
Omopen Server Return 61 
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OMREAO 94 
omread 62 
OMWRTT 96 
omwricc 64, 67 
open potnes dacabas 6 

P 

parameter cable 4 
process variables 2 
process-control objects 1 



S 

scanner connection cable 8 
scanner database 6 
server connection cable 8 
sec_cnfLlist 22 
set_con£rm 20 
set_confirm_list 39 
SETCON 82 
SETVAL 84 
setval 24, 43 
secvaMisc 26 
shared objects 1 
st_om_setvaI 31 
st_o mset_co nfirm 28 
st_set_list 40 
st_setcnf 34 
st_setiist_confirm 37 



U 

UNIMPO 103 
unimport 78 



V 

variable scan race 3 
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